home *** CD-ROM | disk | FTP | other *** search
/ Best of Shareware / Best of PC Windows Shareware 1.0 - Wayzata Technology (7111) (1993).iso / mac / DOS / PROGRAMG / ZI_123 / ZINSTALL.DOC < prev    next >
Text File  |  1992-08-20  |  113KB  |  3,291 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.                                       Z/Install
  29.                                      Version 1.0
  30.  
  31.                       (c) Copyright 1992  SpeedSOFT Development
  32.                                 All rights reserved.
  33.  
  34.                                    July 1st, 1992
  35.  
  36.  
  37.                            The ultimate developer's helper       SpeedSOFT Development                                                     
  38.  
  39.  
  40.       TABLE OF CONTENTS                                                     PAGE
  41.  
  42.  
  43.       Chapter 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    3
  44.            1.1 - What is Z/Install? . . . . . . . . . . . . . . . . . . . .    4
  45.            1.2 - The installation executable  . . . . . . . . . . . . . . .    4
  46.            1.3 - Archiving files  . . . . . . . . . . . . . . . . . . . . .    4
  47.            1.4 - Distribution disks . . . . . . . . . . . . . . . . . . . .    4
  48.  
  49.       Chapter 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  50.            A general overview of the script language  . . . . . . . . . . .    6
  51.            2.1 - How to write a script file . . . . . . . . . . . . . . . .    7
  52.            2.2 - Rules of the ZSL compiler  . . . . . . . . . . . . . . . .   11
  53.            2.3 - Limitations of the ZSL compiler  . . . . . . . . . . . . .   12
  54.            2.4 - Single-variable modification operators . . . . . . . . . .   12
  55.            2.5 - Format control strings . . . . . . . . . . . . . . . . . .   12
  56.            2.6 - String codes . . . . . . . . . . . . . . . . . . . . . . .   14
  57.            2.7 - Tokens in ZSL  . . . . . . . . . . . . . . . . . . . . . .   15
  58.            2.8 - The color strings  . . . . . . . . . . . . . . . . . . . .   15
  59.            2.9 - The Set... functions . . . . . . . . . . . . . . . . . . .   16
  60.            2.10 - Global variables  . . . . . . . . . . . . . . . . . . . .   17
  61.            2.11 - Using the compiler  . . . . . . . . . . . . . . . . . . .   17
  62.            2.12 - The Precompiling Stage  . . . . . . . . . . . . . . . . .   18
  63.            2.13 - Final notes . . . . . . . . . . . . . . . . . . . . . . .   19
  64.  
  65.       Chapter 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   20
  66.            3.1 - A general overview of the .ZPK format  . . . . . . . . . .   20
  67.            3.2 - Command line switches for ZPACK.EXE  . . . . . . . . . . .   20
  68.            3.3 - Self-extracting archives . . . . . . . . . . . . . . . . .   22
  69.  
  70.       Chapter 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   23
  71.            4.1 - Distribution building, Step one  . . . . . . . . . . . . .   23
  72.            4.2 - Distribution building, Step two  . . . . . . . . . . . . .   24
  73.            4.3 - What do I do with the script file OPTDist creates? . . . .   24
  74.            4.4 - Disadvantages of using OPTDist . . . . . . . . . . . . . .   24
  75.  
  76.       Appendix A  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   25
  77.  
  78.       Appendix B  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   47
  79.            B.1 - The [GROUPS] Section . . . . . . . . . . . . . . . . . . .   47
  80.            B.2 - The [FILES] Section  . . . . . . . . . . . . . . . . . . .   47
  81.            B.3 - The [PATHS] Section  . . . . . . . . . . . . . . . . . . .   47
  82.            B.4 - The [DISKS] Section  . . . . . . . . . . . . . . . . . . .   48
  83.  
  84.       Appendix C  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   49
  85.  
  86.       Appendix D  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   52
  87.  
  88.       Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   53
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.       2                                                           Z/Install User's Guide
  97.  
  98.  
  99.                                        Chapter 1
  100.                                  Welcome to Z/Install!
  101.  
  102.       Thank you for taking the time to evaluate Z/Install, version 1.0.  We hope
  103.       you  find  our product  useful,  simple to  understand,  and most  of all,
  104.       intuitive.  Many hours of work have gone into the design of Z/Install, and
  105.       more still  have been  devoted to rigorous  testing and  benchmarking. One
  106.       factor has been paramount  in the development of Z/Install:   to produce a
  107.       system that is powerful and versatile in design and function, with ease of
  108.       use that is surpassed by none. 
  109.  
  110.  
  111.       1.1 - What is Z/Install?
  112.       --------------------------------------------
  113.  
  114.       Z/Install is  a multi-purpose  developer's helper.   It has  three primary
  115.       functions:   To create an  installation program, to  archive and store the
  116.       developer's software,  and to  create distribution disk  sets.   All three
  117.       sections of  Z/Install use an  original Textual User Interface  (TUI) with
  118.       eye-pleasing VGA support  and an online, context-sensitive  HyperText help
  119.       system, to make sure the user's time is well-spent.
  120.  
  121.  
  122.       1.2 - The installation executable
  123.       --------------------------------------------
  124.  
  125.       Z/Install uses  its powerful compiler  to read a user-written  script file
  126.       and  produce  an installation  program.    The  program contains  all  the
  127.       information  about the  product  that  it will  install,  and requires  no
  128.       external  files to  run properly,  except those  that make  up the  user's
  129.       application.  
  130.  
  131.       See Chapter  2  -  Writing  an  installation script  file  -  for  a  full
  132.       explanation on the versatile script language used by Z/Install.
  133.  
  134.  
  135.       1.3 - Archiving files
  136.       --------------------------------------------
  137.  
  138.       Z/Install  includes two archiving  programs.  One  is command-line driven,
  139.       and the other boasts a windowed user interface.   Both of these create and
  140.       maintain  archives that  are  placed  on the  distribution  disks and  un-
  141.       archived by the installation executable.   The archivers also compress the
  142.       files that are stored, with the result that much less space is required on
  143.       the distribution disks.   This alone  can save  the user a  great deal  of
  144.       money  on disks.  It also  provides a method of  storing many files in one
  145.       single 'pack' - much easier than maintaining tens of distribution files.  
  146.  
  147.       See Chapter 3 - The archiving programs - for information about the 'packs'
  148.       and the programs that use them.
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.                                                                                3       SpeedSOFT Development                                                     
  156.  
  157.  
  158.       1.4 - Distribution disks
  159.       --------------------------------------------
  160.  
  161.       While   other  installation  packages   force  you  to   create  your  own
  162.       distribution  disks,  Z/Install  provides a  totally  automated  method of
  163.       performing the task.  OPTDist -  our most intuitive program - will  create
  164.       your distribution disks for you!  Not only that - it will format and label
  165.       your disks, copy  your files, and save you money!   OPTDist will read your
  166.       distribution  files,  prompt you  for  a  disk media  size,  and,  using a
  167.       sophisticated algorithm,  compute the order  in which files are  placed on
  168.       your disks  that takes up  the least number  of disks!   It even  writes a
  169.       script for the installation executable to read that tells it where to find
  170.       the files!  How's that for automation?
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.       4                                                           Z/Install User's Guide
  215.  
  216.  
  217.                                        Chapter 2
  218.                           Writing an installation script file
  219.  
  220.       This is the most important step in  using Z/Install.  Although it helps to
  221.       have an understanding of a programming language,  such as BASIC, it is not
  222.       necessary.
  223.  
  224.  
  225.       A general overview of the script language
  226.       --------------------------------------------
  227.       (This subchapter is intended for use by beginners to programming.)
  228.  
  229.       Think of the script language as the English language.  The verbs in spoken
  230.       language are the actions that are  taken.  In Z/Install's script language,
  231.       the verbs are called functions.  
  232.  
  233.       Functions, like verbs, can take objects.  The objects are the receivers of
  234.       the action.  In ZSL, the objects are called variables.
  235.  
  236.       Variables are like boxes  - they hold things.  In ZSL, there are two types
  237.       of  variables.    The first,  a  string  variable, can  hold  a  number of
  238.       characters.   For  instance, a  string  variable could  hold the  sentence
  239.       "Hello, World!".   In  ZSL, as  in other languages,  string variables  are
  240.       recognised by surrounding  quotation marks (").  More  on string variables
  241.       later.
  242.  
  243.       The second  type of variable  is an integer,  or number, variable.   These
  244.       types of variables can hold any number from 1 to 65,535.  
  245.  
  246.       Variables  are  used to  get  user  input  and  store return  values  from
  247.       functions.  
  248.  
  249.       The second type of data in ZSL is a constant.  A constant is a value which
  250.       cannot be changed,  such as the number 2.   No matter how you  look at it,
  251.       the  number 2  is  always equal  to  2.   Constants and  variables  can be
  252.       interchanged anywhere  in the script  file with the exception of the  left
  253.       value in an assignment (the left side of an equals expression).  
  254.  
  255.       Variables can  be assigned  values by using  the assignment  operator (the
  256.       equals sign).   The left side of an  assignment expression is the variable
  257.       that will hold the data computed from the right side.  For example:
  258.  
  259.       int x          ; Declare an integer
  260.       x = 10*5  ; Assign the value of 10*5 (50) to x.
  261.  
  262.       Now, the value stored in 'x' is 50.  This next example is invalid:
  263.  
  264.       10 = 10*5 ; Error!
  265.  
  266.       Obviously that can't be correct.
  267.  
  268.       In  short, the  right side  of an  assignment expression  is computed  and
  269.       stored in the left side, which must ALWAYS be the name of a variable.
  270.  
  271.       Variables  can be assigned  the return values  of functions.   In the next
  272.  
  273.                                                                                5       SpeedSOFT Development                                                     
  274.  
  275.  
  276.       example, a  variable will  be assigned  the return value  of the  function
  277.       'FileType':
  278.  
  279.       int fe                   ; Declare an integer
  280.       fe = FileType  "NOTEXIST.FIL" ; Check the type of 
  281.                                          ;   NOTEXIST.FIL.
  282.  
  283.       In this  example, again,  the right  side is  computed and  stored in  the
  284.       variable on  the left.   Thus, the integer  'fe' would contain  the return
  285.       code  from the  call to  FileType.   'Fe' could  then be  used in  an 'If'
  286.       statement to branch control to another part of the script file,  depending
  287.       on the results of the call to FileType.
  288.  
  289.  
  290.       2.1 - How to write a script file
  291.       --------------------------------------------
  292.  
  293.            In general, the script file should follow this format:
  294.  
  295.                 A few comments on what the script file installs.
  296.                 Put in the [disks], [groups], [paths] and [files] sections.
  297.                 Use the Set... functions to set up your screen.
  298.                 Declare your variables.
  299.                 Show some kind of welcome message.
  300.                 Get the groups the user wants to install.
  301.                 Get the disk and path the user wants to install to.
  302.                 Call CheckInstOK. 
  303.                 Call BeginInstall
  304.                 Show an exit message
  305.  
  306.  
  307.       The first part  of a script file is the information section.  This section
  308.       contains  the  information  about  the  application  that  Z/Install  will
  309.       install.
  310.  
  311.       The  first section is the [DISKS]  section.  This is  used to identify the
  312.       different distribution disks and to inform the user which disk to insert.
  313.  
  314.       The format of each line in the [DISKS] section is:
  315.  
  316.       Disk number : Volume label : Descriptive name
  317.  
  318.       The disk number is used in the  [FILES] section.  Z/Install uses this disk
  319.       number to determine the source disk of each file.  
  320.  
  321.       The volume label is used to make sure the user inserts the correct disk.
  322.  
  323.       The descriptive name is used in the prompt requesting the user to insert a
  324.       new disk.  When a disk change is required, the user will see a window with
  325.       the following text:
  326.  
  327.                              Please insert the disk marked
  328.                                   "Descriptive name"
  329.                                      in the drive.
  330.  
  331.  
  332.       6                                                           Z/Install User's Guide
  333.  
  334.  
  335.       The [DISKS] section is mandatory, however, Z/Install will ignore it if the
  336.       source  drive is a hard disk.  In  this case, all files are expected to be
  337.       located in the current directory on the source hard disk.
  338.  
  339.       An example [DISKS] section is:
  340.  
  341.       [DISKS]
  342.       1:Z/Install Disk 1
  343.       2:Z/Install Disk 2
  344.       [END]
  345.  
  346.       Each of the information sections is terminated with the line "[END]".
  347.  
  348.       Next comes the [GROUPS] section.  This  section is optional.  Suppose your
  349.       application  were a  word  processor,  and it  included  utilities like  a
  350.       spellchecker  and a thesaurus.  The user can opt to install only the parts
  351.       of your  application that  are wanted.   These  parts are  set up  in this
  352.       section.
  353.  
  354.       Each line in the [GROUPS] section is formatted as follows:
  355.  
  356.       Group number : Group name : Install default (1 = Yes/0 = No)
  357.  
  358.       The group number is used later  in the [FILES] section to determine  which
  359.       group a file belongs to.
  360.  
  361.       The group  name is used to identify the groups to the user.  It appears in
  362.       the Bar Menu displayed by 'GetInstallGroups' (see Appendix A).
  363.  
  364.       An example 
  365.  
  366.       [GROUPS]
  367.       1:Main program:1
  368.       2:Spellchecker:1
  369.       3:Thesaurus:1
  370.       4:Printer files:0
  371.       [END]
  372.  
  373.       In the above example, the 'Printer  files' group will not be installed  by
  374.       default.
  375.  
  376.       Next, write the [PATHS] section.  This section contains the directory tree
  377.       that  Z/Install  will  create  on  the user's  disk  when  installing  the
  378.       application.  The first path is the  directory off the root that Z/Install
  379.       will create.   It is OK to have more than one directory name in this, such
  380.       as:
  381.  
  382.       \APPS\WORDPROC\
  383.  
  384.       Each following path name is  a directory off of the first directory.   For
  385.       example,  if path  number  one  was "\APPS\WORDPROC\",  and  path two  was
  386.       "\SPELL\",  the files  that are  installed  to path  two would  end  up in
  387.       "\APPS\WORDPROC\SPELL\" on the user's disk. 
  388.  
  389.       The [PATHS] section is formatted as follows:
  390.  
  391.                                                                                7       SpeedSOFT Development                                                     
  392.  
  393.  
  394.       Path number : Path
  395.  
  396.       The path  number is used  later in the  [FILES] section to  tell Z/Install
  397.       where to put each file on the destination disk.
  398.  
  399.       [PATHS]
  400.       1:\APPS\WORDPROC\
  401.       2:\SPELL\
  402.       3:\THES\
  403.       4:\PRINTER\
  404.       [END]
  405.  
  406.       Note: Path number one is accessible with the string variable 'RootDir'.
  407.  
  408.       Last is the [FILES] section.   This contains the list of individual  files
  409.       that your  application is  made up  of.  The  file list  follows a  simple
  410.       format:
  411.  
  412.       FILENAME.EXT : Path Number : Disk Number : Compressed (1/0) : Group Number
  413.  
  414.       'Path Number' is the number of the path  that the file will reside in when
  415.       installed.
  416.  
  417.       'Disk Number' is the number of the disk that the file is to be found on.
  418.  
  419.       'Compressed (1/0)'  is the number 1  or 0, depending  on if the file  is a
  420.       ZPack archive.   If it is,  the contents of  the archive will  be unpacked
  421.       into the path, instead of the file itself.
  422.  
  423.       'Group Number'  is the  number of  the group  that this  file is  part of.
  424.       Then, the file  will only be  installed if its  group was selected by  the
  425.       user.  If this number is 0, the file will always be installed.
  426.  
  427.       [FILES]
  428.       MAIN.ZPK    : 1 : 1 : 1 : 1
  429.       SPELL.ZPK   : 2 : 1 : 1 : 2
  430.       THES.ZPK    : 3 : 2 : 1 : 3
  431.       PRINTER.ZPK : 4 : 2 : 1 : 4
  432.       [END]
  433.  
  434.       The  next step in the script file is  to use the 'Set...' functions to set
  435.       up  the  colors  and style  of  the  Installation Program.    See  2.9 for
  436.       information.
  437.  
  438.       If your script file uses any variables, they should be declared now.  This
  439.       is the best place to declare them because they are easy to find if they're
  440.       always  at  the  top  of the  script,  and  they  will  also be  available
  441.       throughout the entire script.
  442.  
  443.       It's  a good  idea to  show your  welcome screen here.   Use  the 'Dialog'
  444.       function to display some information  about your application, and what its
  445.       requirements are.  An example:
  446.  
  447.       Dialog 0, 0
  448.  
  449.  
  450.       8                                                           Z/Install User's Guide
  451.  
  452.  
  453.           @CWelcome to Application v1.0!  This program will install Application 
  454.          @Con your hard disk and help you get started with using it.
  455.  
  456.       EndDialog
  457.  
  458.       Call  'GetInstallGroups' here  to  ask the  user  which groups  are  to be
  459.       installed.  
  460.  
  461.       Call 'GetInstallationDrive' to determine the destination drive.
  462.  
  463.       Use  a dialog  to ask the  user which  path to  install to.   This  is not
  464.       mandatory, because Z/Install will default to path number one (as set up in
  465.       the [PATHS] section).  An example for doing this is:
  466.  
  467.       Dialog 0, 0
  468.  
  469.           @CPlease enter the path in which to install Application:
  470.  
  471.           @ERootDir
  472.  
  473.       EndDialog
  474.  
  475.       See the function 'Dialog' in  the Appendix A for information  on receiving
  476.       input and writing dialogs.
  477.  
  478.       If you  have turned off the option  to use a hard disk  as a source drive,
  479.       call  'CheckInstOK' here  to confirm that  the user  is installing  from a
  480.       floppy disk.
  481.  
  482.       Now, everything  is ready to  go!  Call  'BeginInstall' here to  start the
  483.       installation.
  484.  
  485.       After  the installation is  finished, use 'Dialog'  again to show  an exit
  486.       message, and call 'ExitScript' to exit Z/Install.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.                                                                                9       SpeedSOFT Development                                                     
  510.  
  511.  
  512.       2.2 - Rules of the ZSL compiler
  513.       --------------------------------------------
  514.  
  515.            -    Strings  are  declared with  the  STR  function.   Integers  are
  516.                 declared with the INT function.
  517.  
  518.            -    The  ZSL interpreter has  an expression evaluator  that supports
  519.                 the following  operators: ()*/+-=.  It uses  the standard BEDMAS
  520.                 rules to evaluate the expressions.  For example:
  521.  
  522.                 x = (10*(5+1))/(20-10)
  523.  
  524.            -    Variables may be  used in place of constants  almost anywhere in
  525.                 the script file.  For example:
  526.  
  527.                 x = (10*b)+y
  528.  
  529.            -    Return  values from  functions  don't  have to  be  stored in  a
  530.                 variable.  For example, GetChoice returns a string variable, but
  531.                 in this instance, we just wait for any key:
  532.  
  533.                 GetChoice ""   ; Wait for any key, we don't care which.
  534.  
  535.            -    Variables types are NOT interchangeable.   If a function returns
  536.                 a  string  variable,  the  variable  on the  left  side  of  the
  537.                 expression MUST be a string  variable, and vice-versa.  The same
  538.                 goes for function parameters.
  539.  
  540.            -    Variables and  labels (see  function LABEL)  cannot be  declared
  541.                 inside an 'If' loop.
  542.  
  543.            -    ZSL is case-insensitive.  For example, calls to 'SetDialogColor'
  544.                 and 'SETDIALOGCOLOR' would have the same effect.
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.       10                                                           Z/Install User's Guide
  569.  
  570.  
  571.       2.3 - Limitations of the ZSL compiler
  572.       --------------------------------------------
  573.  
  574.            -    The compiled data in the script file cannot exceed 64k.  This is
  575.                 not a problem since a dense, 500 line script file  only produces
  576.                 about 7k of compiled data.
  577.            -    Strings can be a maximum of 255 characters long.
  578.            -    There can only be one expression on each line.
  579.            -    Lines are  commented with semicolons.   As soon as  the compiler
  580.                 intercepts  a  semicolon  that is  outside  quotation  marks, it
  581.                 ignores the rest of the line.
  582.            -    There can  be up  to 50  integer and  50 string  variables in  a
  583.                 script file.
  584.            -    The maximum line length is 255 characters.
  585.  
  586.  
  587.       2.4 - Single-variable modification operators
  588.       --------------------------------------------
  589.  
  590.       These  modification  operators   are  used  for   single-variable  integer
  591.       arithmetic:
  592.  
  593.       Modifier       Description                                          Sample
  594.       --------------------------------------------
  595.       +=        Plus equals                                                 x+=5
  596.       -=        Minus equals                                                x-=5
  597.       ++        Increment by one                                             x++
  598.       --        Decrement by one                                             x--
  599.       *=        Times equals                                                x*=2
  600.       /=        Divide equals                                               x/=2
  601.       &=        Bitwise AND equals                                        x&=128
  602.       |=        Bitwise OR equals                                         x|=128
  603.  
  604.  
  605.       Therefore,
  606.  
  607.            x += 5         is the same as                               x = x + 5
  608.            x /= 4                                                      x = x / 4
  609.            x ++                                                        x = x + 1
  610.  
  611.       and so on.  This is just a shorthand method to save time and space.
  612.  
  613.  
  614.       2.5 - Format control strings
  615.       --------------------------------------------
  616.  
  617.       In ZSL, as in  C, there is a facility for creating  formatted strings.  It
  618.       is used this way:
  619.  
  620.            variablename(format specifier)
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.                                                                               11       SpeedSOFT Development                                                     
  628.  
  629.  
  630.       The format specifier is arranged as follows:
  631.  
  632.            [Optional Direction]
  633.            [Optional fill character]
  634.            Minimum number of characters
  635.  
  636.       1. Direction
  637.  
  638.       This  comes before  anything else.    The default  justification is  Right
  639.       justification, which pads on the left:
  640.  
  641.                 John Doe
  642.               Gale Jones
  643.       ^^^^^^^^^^^^^^^^^^ = Left padded
  644.  
  645.       If  you wish  to have  left  justification, then  you must  place  the '-'
  646.       character before the rest of the format specifier.
  647.  
  648.       2. Fill character
  649.  
  650.       This is also optional.  If you have integers to be displayed, and you want
  651.       to fill the empty digits with, say, a '0' character, your format specifier
  652.       would look like this:
  653.  
  654.            variablename(030)
  655.  
  656.       The first character  in the format specifier is the fill character.  Note:
  657.       You cannot  use  positive  numbers for  your  fill character  if  you  are
  658.       justifying an integer!  Fill  characters only work on right-justified text
  659.       (they will just be ignored on left-justified text).
  660.  
  661.       3. Number of characters
  662.  
  663.       This is the  minimum number of characters  that will be displayed.  If the
  664.       length  of the variable is  less than this number,  it will be padded with
  665.       your fill character. If the variable  to be displayed is longer than  this
  666.       number, it will be truncated to fit it.  Look at the following example:
  667.  
  668.            str name = "John Doe"
  669.            str formattedname
  670.            formattedname = name(20)
  671.  
  672.       'formattedname' would now contain:
  673.  
  674.                  John Doe
  675.       ^^^^^^^^^^^^^^^^^^^ = 20 characters.
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.       12                                                           Z/Install User's Guide
  687.  
  688.  
  689.       If you were to put in:
  690.  
  691.       formattedname = name(-20)
  692.  
  693.       It would contain:
  694.  
  695.       John Doe
  696.       ^^^^^^^^^^^^^^^^^^^ = 20 characters.
  697.  
  698.       Some examples:
  699.  
  700.            An integer, padded  on the left with  spaces to make a  MINIMUM of 10
  701.            characters:    my_int(10) (The default padding character is a space).
  702.  
  703.            A string, padded on the left with pound signs to make a MINIMUM of 15
  704.            characters:    my_str(#15)
  705.  
  706.            A  string, padded  on the right  with stars  to make a  minimum of 20
  707.            characters:    my_str(-*20)
  708.  
  709.  
  710.       Format control strings can also be stacked, as follows:
  711.  
  712.            str name = "George"
  713.            str date = "07/01/92"
  714.            str time = "10:34:42"
  715.  
  716.            str formatted = name(-20), " - ", date(-8), " - ", time(-8), "\n"
  717.  
  718.       Note:     In 'stacked'  format  strings, each  variable/constant  is  also
  719.                 separated with a comma, just like function parameters.
  720.  
  721.       From the above example, the string 'formatted' would now contain:
  722.  
  723.            "George               - 07/01/92 - 10:34:42 (linefeed)"
  724.  
  725.             ^^^^^^^^^^^^^^^^^^^^ =  20    characters,    as    specified    with
  726.                                     "name(-20)". Don't  forget that  putting the
  727.                                     minus sign  before  the  minimum  number  of
  728.                                     characters left-justifies the text.
  729.  
  730.       2.6 - String codes
  731.       --------------------------------------------
  732.  
  733.       Z/Install  allows you  to embed  certain  control codes  in your  strings.
  734.       These control codes make it easier for you to put special characters, such
  735.       as linefeeds  and tabs,  into your  script.   These codes  begin with  the
  736.       backslash  character  (\),  and  are  followed  by  one  or  more  control
  737.       characters.  This is the table of codes:
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.                                                                               13       SpeedSOFT Development                                                     
  746.  
  747.  
  748.       What you write                                           What gets put in 
  749.       --------------------------------------------
  750.       \\                                                 One backslash character
  751.       \t                                                           Tab (ASCII 9)
  752.       \f                                                     Formfeed (ASCII 12)
  753.       \n                                                     Linefeed (ASCII 10)
  754.       \r                                              Carriage Return (ASCII 13)
  755.       \xXX                                                        Hexadecimal XX
  756.       \a                                                          Bell (ASCII 7)
  757.       \b                                                     Backspace (ASCII 8)
  758.  
  759.       Example:  
  760.  
  761.            str my_str = "$\x04\agy\b"
  762.  
  763.       as seen by the compiler, would be: $(HEX 04)(BELL)gy(BACKSPACE)
  764.  
  765.  
  766.       2.7 - Tokens in ZSL
  767.       --------------------------------------------
  768.  
  769.       What it is               Example        Case Sensitive?       What it does
  770.       --------------------------------------------
  771.       Function                 FileType       N                 Performs actions
  772.       Operators                =, +=, >       N           Compares/Modifies Data
  773.       Labels                   my_label       N              Used for GOTO/GOSUB
  774.       Operands
  775.        Integers
  776.            Variables my_int                   N                      Stores data
  777.            Decimal Const       1, 300, 20
  778.            Hexadec. Const      0x100, 0xFF    N
  779.            Char. Const         ')' 'R'        Y
  780.        Strings
  781.            Variables           my_str         N                      Stores data
  782.            String Const        "Hi", "Bye"    Y
  783.  
  784.  
  785.       2.8 - The color strings
  786.       --------------------------------------------
  787.  
  788.       No more messing around with attribute bytes - Z/Install has a color string
  789.       parser built  in!  It's as easy  as it sounds; just type  in the color you
  790.       want.   These strings are  used for  the Set...Color  functions, and  they
  791.       follow this format:
  792.  
  793.       [Bright]Color<On>[Bright]Color
  794.  
  795.       Where 'Color' is:
  796.  
  797.            Black     Blue
  798.            Green     Cyan
  799.            Red  Magenta
  800.            Brown     White
  801.  
  802.       If you  put  'Bright' before  the  'Color', it  will  be a  high-intensity
  803.  
  804.       14                                                           Z/Install User's Guide
  805.  
  806.  
  807.       version  of the darker  color.  Brown  turns to yellow.   ColorStrings are
  808.       case-insensitive.
  809.  
  810.       Example:  SetDialogColor BrightBrownOnBlue
  811.  
  812.       Note:     If  you specify  a 'Bright'  background color,  you should  call
  813.                 UseHighIntensityBGColors.    Otherwise,   the  background  won't
  814.                 change,  and  the  foreground  will  blink.    This  is  a  BIOS
  815.                 limitation.
  816.  
  817.  
  818.       2.9 - The Set... functions
  819.       --------------------------------------------
  820.  
  821.       ZSL uses these Set... functions to control its screen and input routines:
  822.  
  823.       Function       Parameter                                        Sets what?
  824.       --------------------------------------------
  825.       SetBackColor        ColorString                           Background color
  826.       SetBackChar         ASCII 1-255                       Background fill char
  827.       SetDialogColor      ColorString                               Dialog color
  828.       SetDialogStyle      StyleString*                       Dialog border style
  829.       SetPrintColor       ColorString                          Dialog text color
  830.       SetExitMessage      1-80 char str                   Text displayed at exit
  831.       SetInputColor       ColorString                       Color for user input
  832.       SetInputFill        ASCII 1-255                 Fills empty space in input
  833.       SetBarNormalColor   ColorString                   BarMenu unselected color
  834.       SetBarHighColor     ColorString                     BarMenu selected color
  835.       SetBarCharColor     ColorString                       BarMenu hotkey color
  836.       SetDialogShadows    On/Off                           Dialog shadows on/off
  837.       SetWarnColor        ColorString                 Error/Warning dialog color
  838.       SetWarnTxtColor     ColorString                   Error/Warning text color
  839.       SetExplode          ExplString*                          Exploding windows
  840.       SetExplodeSnd       On/Off                                 Exploding sound
  841.       SetExplodeType      1 or 2                                  Exploding type
  842.  
  843.  
  844.            For  SetExplodeType,  1  sets slow,  smooth  explosions,  and 2  sets
  845.            faster, explosions.
  846.  
  847.            * StyleString is: Single, Double, Thick, or None.
  848.            *  ExplString  is :  All,  Dialog_Only,  Dialog_Warn, or  None.  Sets
  849.            explode  for  windows,  only  dialogs, dialogs  and  warnings,  or no
  850.            explosions, respectively. 
  851.  
  852.  
  853.       The Set... functions  should all be called after  the information sections
  854.       and before any other function calls.
  855.  
  856.       Note:     If  the user's  video display  is  monochrome, the  installation
  857.                 program will set  its colors to a hard-coded  default for black-
  858.                 and-white screens.  This way,  the monochrome users will  always
  859.                 be able to see the screens properly.
  860.  
  861.       2.10 - Global variables
  862.  
  863.                                                                               15       SpeedSOFT Development                                                     
  864.  
  865.  
  866.       --------------------------------------------
  867.  
  868.       Z/Install has 20 global variables, most of which are used for system auto-
  869.       detection.  These variables can  be accessed anywhere in the script  file.
  870.       They are:
  871.  
  872.       Name      Type [Int/Str]                                       Description
  873.       -------------------------------------------- 
  874.       EgaVga         Int                            1 if EGA, 2 if VGA, 0 if CGA
  875.       ExtendedMemory Int                                Int 15h memory in kbytes
  876.       XMSMemory      Int                                Raw XMS memory in kbytes
  877.       Joystick       Int                                 1 if joystick installed
  878.       MathCPU        Int                              1 if coprocessor installed
  879.       ConvMemory     Int                      Base conventional memory in kbytes
  880.       EMSMemory      Int                                    EMS memory in kbytes
  881.       ANSISYS        Int                 1 if ANSI.SYS (or equivalent) installed
  882.       OSMinor        Int                             DOS version number  (major)
  883.       OSMajor        Int                              DOS version number (minor)
  884.       BWColor        Int                        1 if color, 0 if black and white
  885.       SourceType     Int             Source disk size (K) - 360, 720, 1200, 1440
  886.       NumArgs        Int                        Number of command-line arguments
  887.       FileHandles    Int                    Number of DOS file handles available
  888.       Buffers        Int                         Number of DOS buffers available
  889.       ProcessorType  Str                              "186", "286", "386", "486"
  890.       InstalledOK    Int                                                See note
  891.       Instdrv        Str                    Drive letter of the destination disk
  892.       Rootdir        Str                        Root dir on the destination disk
  893.       NeededSpace    Int                           Space free needed to install*
  894.  
  895.            * This variable is automatically set.   If, for any reason, it  needs
  896.            to be changed, make sure it is set to the right value.
  897.  
  898.       Note:     The  integer  variable  'InstalledOK'  gets  set  after  calling
  899.                 'BeginInstall'.     If   the  user  aborted   the  installation,
  900.                 'InstalledOK' gets set to 0.  Otherwise it is set to 1.
  901.  
  902.  
  903.       2.11 - Using the compiler
  904.       --------------------------------------------
  905.  
  906.       The compiler is 'ZINSTALL.EXE'.  It has a simple command line interface:
  907.  
  908.       The first parameter is the name of the script file to compile.  The second
  909.       is the name of the output file to create.  
  910.  
  911.       Suppose you had written a script file called DEMO.ZSL.  To compile it, you
  912.       would enter the following at the DOS prompt:
  913.  
  914.       C:\ZINSTALL> zinstall demo 
  915.  
  916.       This  would produce  DEMO.EXE, assuming  there  are no  errors during  the
  917.       compilation.   Note that  the extension of  the script file  (.ZSL) is not
  918.       specified.  This is because the compiler  assumes the .ZSL extension if no
  919.       other extension is provided.  
  920.  
  921.  
  922.       16                                                           Z/Install User's Guide
  923.  
  924.  
  925.       The default  output filename  is 'filename.EXE',  where 'filename'  is the
  926.       name of  the script that is compiled.   If you want to  change the name of
  927.       the output file, simply specify it on the second parameter.  For example:
  928.  
  929.       C:\ZINSTALL> zinstall demo install
  930.  
  931.       This example would  produce INSTALL.EXE.  The extension of the output file
  932.       will always be '.EXE', even if another extension is provided.
  933.  
  934.       The compiler will make three passes on the script file.  The first pass is
  935.       called the 'precompiling stage'.  See Chapter 2.12 for information on this
  936.       important phase.   The second and  third passes translate  the script file
  937.       into binary information that the installation executable can interpret.   
  938.  
  939.       If there are any errors or  warnings during the compilation, they will  be
  940.       written to the  file 'ZINSTALL.LOG', unless the first  parameter passed to
  941.       Z/Install is /x.   See Appendix  C for a list  of all the errors  that can
  942.       occur.
  943.  
  944.  
  945.       2.12 - The Precompiling Stage
  946.       --------------------------------------------
  947.  
  948.       During this important  stage, Z/Install looks for  certain instructions in
  949.       the script file called precompiler  directives.  These directives are used
  950.       to instruct Z/Install when it interprets the script.
  951.  
  952.       The directives  are identified with a preceding pound  sign, '#'.  This is
  953.       so the  precompiler can  easily and  quickly tell  them  apart from  other
  954.       script file commands.
  955.  
  956.       In Version 1.0, there are only two directives.  They are:
  957.  
  958.  
  959.       #include filename   This directive instructs  the compiler to include  the
  960.                           contents of 'filename' in the script file.  'Filename'
  961.                           cannot have any precompiler directives in it.
  962.  
  963.       #end                This directive instructs the compiler to stop  reading
  964.                           the  script file.  Everything in the script after this
  965.                           directive will be ignored.
  966.  
  967.       Precompiler  directives,  like  all  other  keywords  in  ZSL,  are  case-
  968.       insensitive.
  969.  
  970.  
  971.       2.13 - Final notes
  972.       --------------------------------------------
  973.            Here are a few pointers to get you started with ZSL:
  974.  
  975.            - Comment your  scripts.  You'll hate the feeling of asking, "Why did
  976.            I put that in?".   You'll hate it even more when you  take it out and
  977.            your script doesn't run!
  978.  
  979.            - Test your work.   Make sure your script runs smoothly  on more than
  980.  
  981.                                                                               17       SpeedSOFT Development                                                     
  982.  
  983.  
  984.            one computer.  
  985.  
  986.            -  If your script modifies AUTOEXEC.BAT  and/or CONFIG.SYS, make sure
  987.            the  script asks the  user if they  want direct  modifications, or if
  988.            they  want  the  installation  program  to create  a  file  with  the
  989.            recommended changes.   Users  HATE it when  programs make  changes to
  990.            their boot files without their knowledge.
  991.  
  992.            - Call us with any problems.  See Appendix D for information.
  993.  
  994.       You are now ready to write your installation script!  Appendix A lists all
  995.       the script commands in alphabetical order. 
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.       18                                                           Z/Install User's Guide
  1041.  
  1042.  
  1043.                                        Chapter 3
  1044.                                 The Archiving Programs
  1045.  
  1046.       Z/Install is packaged with two versions of its archive program, ZPack. One
  1047.       version is used from  the command line (it's the one  we'll discuss here),
  1048.       and the other  has a menu-driven interface.  Both produce the same type of
  1049.       archive,  the  .ZPK  format.    You'll find  both  programs  in  the ZPACK
  1050.       subdirectory.  They are ZPACK.EXE and ZPMENU.EXE.
  1051.  
  1052.  
  1053.       3.1 - A general overview of the .ZPK format
  1054.       --------------------------------------------
  1055.       (This is  for those who are interested in  the technical aspects of ZPack,
  1056.       and is by no means required reading)
  1057.  
  1058.       Each  archive file  begins with  a  signature comprised  of the  following
  1059.       characters: 1,ZPK,1.  This  is used to determine if the  file really is of
  1060.       the .ZPK format.  
  1061.  
  1062.       Next, the files come in  sequence, with a header before each.   The header
  1063.       simply stores information about the file, such as the CRC-32 value and the
  1064.       file date/time.
  1065.  
  1066.       The files are stored in no particular order.  There is a maximum of 65,535
  1067.       files  per archive, and no limit  on the size of  the archive or the files
  1068.       inside it.  The files are stored without a path name.
  1069.  
  1070.  
  1071.       3.2 - Command line switches for ZPACK.EXE
  1072.       --------------------------------------------
  1073.  
  1074.       ZPack has a relatively simple command line syntax.  It is as follows:
  1075.  
  1076.            ZPACK <action> [/options] <filename[.ZPK]> [filenames...]
  1077.  
  1078.            The parsing syntax for the command line is:
  1079.  
  1080.            [] -  Anything enclosed  in these  is optional  in most  cases.   For
  1081.            example, the  [filenames...] parameter is  not required  to view  the
  1082.            contents of an archive, but is  definitely required to add or  delete
  1083.            files from the archive.
  1084.  
  1085.            <> -  Parameters enclosed in  these are mandatory and  cannot be left
  1086.            out.  Doing so will cause ZPack to report an error.
  1087.  
  1088.            ...- Means one  or more of  the same type of  parameter may be  used.
  1089.            This  means  you   can  have  multiple  filenames/wildcards   in  the
  1090.            [filenames] parameter, separated with spaces.
  1091.  
  1092.       Note:     When  specifying the archive name, it is not necessary to put in
  1093.                 the extension (.ZPK).  If you  DO put an in extension,  however,
  1094.                 ZPack will  look  for the  specified file  instead of  appending
  1095.                 .ZPK.
  1096.  
  1097.       The parameter <action> is the function that you want ZPack to  perform. It
  1098.  
  1099.                                                                               19       SpeedSOFT Development                                                     
  1100.  
  1101.  
  1102.       can be one of the following:
  1103.  
  1104.            A -  Add files (create  archive).  If  the archive file  specified is
  1105.            missing,  it  will  be  created.     Wildcards  are  allowed  in  the
  1106.            [filenames...] parameter. 
  1107.  
  1108.                      Sample:  zpack a program *.exe *.dat
  1109.  
  1110.            D - Delete  files.   The files  specified in  [filenames...] will  be
  1111.            deleted from the  archive.  Wildcards are allowed.  ZPack will prompt
  1112.            you to Save the Changes (Y/N) after it deletes the files, so you have
  1113.            a chance to make a mistake.
  1114.  
  1115.                      Sample:  zpack d program *.exe *.dat
  1116.  
  1117.            F  -  Freshen files.    This  is  a  powerful command.    ZPack  will
  1118.            sequentially  read the file records in the archive and match the date
  1119.            and time  of each one to the  date and time of the  same files on the
  1120.            disk drive. If the file  on the drive is newer  than the file in  the
  1121.            archive, the archived  file will be updated  with the new data.   The
  1122.            [filenames...] parameter is ignored with this action.
  1123.  
  1124.                      Sample:  zpack f program
  1125.  
  1126.            L  - List  files.   This  will give  a summary  of  the files  in the
  1127.            specified  archive.    Wildcards are  allowed  on  the [filenames...]
  1128.            parameter.
  1129.  
  1130.                      Sample:  zpack l program *.exe
  1131.  
  1132.            X - Extract pack.  This will extract the files from  the archive into
  1133.            the current drive/directory.  If the file already exists, you will be
  1134.            prompted to  overwrite  it or  not.   Wildcards  are  allowed on  the
  1135.            [filenames...] parameter.
  1136.  
  1137.                      Sample:  zpack x program *.dat
  1138.  
  1139.            S - Make SFX.   This will convert the specified  archive into a self-
  1140.            extracting .EXE  file.  Please  see section 3.3 for  more information
  1141.            about Self Extracting Archives.
  1142.  
  1143.                      Sample:  zpack s program
  1144.  
  1145.            J  - Make  Junior-SFX.  This  is the  same as  action 's',  except it
  1146.            produces a  smaller .EXE.   Although you save  about 9k in  size, the
  1147.            resulting .EXE does not have as many features as a normal SFX.
  1148.  
  1149.                      Sample:  zpack j program
  1150.  
  1151.  
  1152.       The optional parameter [/options] can be one or more of the following:
  1153.  
  1154.            O - Overwrite  without prompting.   This option  will force ZPack  to
  1155.            overwrite any  existing files  without prompting  when extracting  an
  1156.            archive. Note: Use this with caution, as it may result in  accidental
  1157.  
  1158.       20                                                           Z/Install User's Guide
  1159.  
  1160.  
  1161.            loss of data!
  1162.  
  1163.                      Sample:  zpack x /o program
  1164.  
  1165.            W<disk>- Assign work  drive.  This applies to  all actions. Normally,
  1166.            <disk> would be a RAM disk.   ZPack uses temporary files and a  great
  1167.            deal of disk activity can result when  performing archive operations.
  1168.            Set this to the fastest disk on your system.
  1169.  
  1170.                      Sample:  zpack a /wd program 
  1171.  
  1172.  
  1173.       3.3 - Self-extracting archives
  1174.       --------------------------------------------
  1175.  
  1176.       ZPack has  two  options to  convert normal  archives into  self-extracting
  1177.       archives  (SFX).   SFXs  are run  from  the command  line, like  any other
  1178.       executable program.  When they  are run, they automatically decompress the
  1179.       files that are  stored inside them.   There are two versions of  the ZPack
  1180.       SFX programs; the regular and the junior size.
  1181.  
  1182.       The regular SFX adds  about 17000 bytes  to the size of  the archive.   It
  1183.       also has two command-line options.  They are:
  1184.  
  1185.            O - Overwrite  any existing files without prompting.   If this option
  1186.            is specified, the SFX will  extract the files in the archive  without
  1187.            prompting  whether or  not  to  overwrite any  existing  files.   The
  1188.            default is 'do' prompt.
  1189.  
  1190.            L - List the files in the archive.  This displays the contents of the
  1191.            archive on the screen.
  1192.  
  1193.       The format for the command line options is:
  1194.  
  1195.            EXEFILE   <option>
  1196.  
  1197.       If  the archive has  a file called  'COMMENT.PAK' inside it,  the SFX will
  1198.       read  this  file and  display  its contents  after  the  archive has  been
  1199.       extracted.   'COMMENT.PAK' can also have a special code  in it to tell the
  1200.       SFX  to run a  program after it  has finished extracting  the archive. The
  1201.       code is:
  1202.  
  1203.            *RUN EXENAME.EXE
  1204.  
  1205.       Where EXENAME.EXE is the name of the program you want the SFX to run. This
  1206.       is  great for  authors who  distribute their  programs via  Bulletin Board
  1207.       Systems,  because they  can instruct  the  SFX to  run their  installation
  1208.       program after it extracts the files.
  1209.  
  1210.       The other form of SFX is the junior SFX.  It doesn't have any command line
  1211.       options, and it will always prompt to  overwrite any files it finds on the
  1212.       destination disk.  The junior SFX will ignore COMMENT.PAK.  It  adds about
  1213.       9000 bytes to the size of the archive.
  1214.  
  1215.  
  1216.  
  1217.                                                                               21       SpeedSOFT Development                                                     
  1218.  
  1219.  
  1220.                                        Chapter 4
  1221.                       Two easy steps to build distribution disks
  1222.  
  1223.       Note:     Familiarize yourself with Chapter 2 before reading this chapter.
  1224.  
  1225.  
  1226.       4.1 - Distribution building, Step one
  1227.       --------------------------------------------
  1228.  
  1229.       With the power and  ease of OPTDist at your command, all  you need are two
  1230.       steps (that's right, just  two steps) to build a master  diskette set. The
  1231.       first step is the only one that requires any real work, since step two  is
  1232.       simply 'Run OPTDist'!   Step one involves writing  a special control  file
  1233.       for  OPTDist to read and parse.   This control file contains the paths and
  1234.       files on your hard disk (on  your development computer) that make up  your
  1235.       application. It follows a simple format:
  1236.  
  1237.       ;
  1238.       ; Lines with a semicolon as the FIRST character are ignored.
  1239.       ;
  1240.       ; OPTDist control file for Z/Install.
  1241.       ;    
  1242.       *PATH   C:\TC\ZINSTALL\DIST
  1243.       ;
  1244.       ; That's the path. All the filenames following this (and up until the
  1245.       ; next *PATH statement) are expected to be found in this path.
  1246.       ;
  1247.       ; The file list follows a special format:
  1248.       ;
  1249.       ; FILENAME.EXT  :Path #  :<D> :Compressed [1/0]   :Group #
  1250.       ;
  1251.       ; Where:  Path # - Is the path number, defined in [paths], that
  1252.       ;         this file (or its contents, if it's an archive) 
  1253.       ;         will reside on the user's disk after being
  1254.       ;         installed.
  1255.       ;
  1256.       ;         <D> - Is the actual string <D>.  This gets replaced with ;  the
  1257.       disk number the file is on when OPTDist is run.
  1258.       ;
  1259.       ;         Compressed [1/0] - Is 1 or 0, depending on if the file is 
  1260.       ;         compressed using ZPack or not.
  1261.       ;
  1262.       ;         Group # - Is the group number, defined in [groups], that 
  1263.       ;         this file is part of (If this is zero, this file 
  1264.       ;         will ALWAYS be installed).
  1265.       ;
  1266.       ZINSTALL.ZPK    :0          :<D>        :1                  :1
  1267.       OPTDIST.ZPK     :1          :<D>        :1                  :2
  1268.       DOCS.ZPK        :2          :<D>        :1                  :3
  1269.       PACKARC.ZPK     :3          :<D>        :1                  :4
  1270.       SAMPLES.ZPK     :4          :<D>        :1                  :5
  1271.       FONTS.ZPK       :5          :<D>        :1                  :6
  1272.  
  1273.  
  1274.       This  is  the  actual  OPTDist  control  file  used  to  make  Z/Install's
  1275.  
  1276.       22                                                           Z/Install User's Guide
  1277.  
  1278.  
  1279.       distribution disk set. There is only one *PATH statement because we packed
  1280.       all of our distribution  archives in this directory to avoid cluttering up
  1281.       our development area. 
  1282.  
  1283.       Please note that the file extension for  the OPTDist control files must be
  1284.       .OD.
  1285.  
  1286.  
  1287.       4.2 - Distribution building, Step two
  1288.       --------------------------------------------
  1289.  
  1290.       Now, all you need to do is run OPTDist.  There is online documentation for
  1291.       OPTDist, so we  won't discuss  its commands and  features in this  manual.
  1292.       (Press F1 once you're in OPTDist to bring up the help system.)
  1293.  
  1294.  
  1295.       4.3 - What do I do with the script file OPTDist creates?
  1296.       --------------------------------------------
  1297.  
  1298.       This is the easiest part!  After the [paths] and [groups] sections in your
  1299.       script file, all you have to do is type the line:
  1300.  
  1301.       #include    SCRNAME.OPT
  1302.  
  1303.       Where SCRNAME.OPT  is the name of the file  that OPTDist created after you
  1304.       ran it.  The installation executable will then determine where to find the
  1305.       files at runtime.
  1306.  
  1307.  
  1308.       4.4 - Disadvantages of using OPTDist
  1309.       --------------------------------------------
  1310.  
  1311.       Some  developers  like  to  have their  distribution  disks  organized  by
  1312.       content, such as 'Spellchecker' and  'Thesaurus/Printer program'.  If  you
  1313.       use OPTDist, the script  file it creates will  have a [DISKS]  information
  1314.       section in it.  You may edit the descriptions of the disks  in this script
  1315.       (See Appendix  B), but not the order.  In other words, the disks will have
  1316.       to be named this way:
  1317.  
  1318.            ApplicationName Disk 1
  1319.            ApplicationName Disk 2 
  1320.            etc...
  1321.  
  1322.       They cannot be arranged by content.
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.                                                                               23       SpeedSOFT Development                                                     
  1336.  
  1337.  
  1338.                                       Appendix A
  1339.  
  1340.       This Appendix discusses  the use of Z/Install's script  functions.  Return
  1341.       values  from functions  can  be  stored in  string  or integer  variables.
  1342.       Function parameters can be string  or integer constants and variables, and
  1343.       are separated with commas.  Any extra parameters will be ignored.
  1344.  
  1345.       This is the general outline of a function description:
  1346.  
  1347.       Function Name                                                  Return Type
  1348.       --------------------------------------------
  1349.  
  1350.       Parms:    FunctionName <VARTYPE parm>, ...
  1351.  
  1352.            VARTYPE can be:
  1353.  
  1354.            STRVAR    - A string variable only.
  1355.            STR       - A string variable/constant.
  1356.            BOOL      - A boolean value: =, >=, !=, <=, <, >
  1357.            INTVAR    - An integer variable only.
  1358.            INT       - An integer variable/constant.
  1359.            ANY       - Any string/integer variable/constant.
  1360.            LABEL     - A label defined with LABEL.     
  1361.            COLOR     - A ColorString.
  1362.            ONOFF     - "On" or "Off".
  1363.            FORMAT    - A formatted control string OR a string 
  1364.                      variable/constant.
  1365.  
  1366.       Returns:  (The value it returns, if any)
  1367.  
  1368.       Desc:     (A long description)
  1369.  
  1370.       Example:  (A Sample usage)
  1371.  
  1372.       Some functions  return an 'Escape Integer'.   The function 'SetEscapeType'
  1373.       is used  to tell Z/Install how to handle the  user pressing <ESC>.  If the
  1374.       user presses <ESC>, Z/Install will  automatically exit OR the return value
  1375.       from these functions will be 0,  depending on the call to 'SetEscapeType'.
  1376.       The default is to let Z/Install handle the <ESC> key by asking the user if
  1377.       they want to exit.
  1378.  
  1379.       Some functions can be repositioned with the 'At' command.  If the function
  1380.       call has "@(x,y)" on its end, where 'x'  is the column and 'y' is the row,
  1381.       the function's  output will start at x,y  on the screen.  If  'x' is zero,
  1382.       the output will be centered horizontally.  If 'y' is zero, the output will
  1383.       be centered vertically.  For example:
  1384.  
  1385.       GetInstallationDrive @(0,4)   ; Start on line 4, centered horizontally.
  1386.       GetInstallationDrive @(3,4)   ; Start on column three, line 4.
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.       24                                                           Z/Install User's Guide
  1395.  
  1396.  
  1397.       AddAuto                                                               None
  1398.       --------------------------------------------
  1399.  
  1400.       Parms:    AddAuto <FORMAT text>
  1401.  
  1402.       Returns:  None
  1403.  
  1404.       Desc:     Adds 'text' to AUTOEXEC.BAT.  It  looks in the root directory of
  1405.                 the destination drive.
  1406.  
  1407.       Example:  AddAuto "ECHO OFF"
  1408.  
  1409.  
  1410.       AddConfig                                                             None
  1411.       --------------------------------------------
  1412.  
  1413.       Parms:    AddConfig <FORMAT text>
  1414.  
  1415.       Returns:  None
  1416.  
  1417.       Desc:     Adds 'text'  to CONFIG.SYS.   It looks in the  root directory of
  1418.                 the destination drive.
  1419.  
  1420.       Example:  AddConfig "DEVICE=ANSI.SYS"
  1421.  
  1422.  
  1423.       BarMenu                                                               None
  1424.       --------------------------------------------
  1425.  
  1426.       Parms:    BarMenu  <INTVAR  selection>,  <INT  len>,  <INT   start>,  <INT
  1427.                           removewin>
  1428.  
  1429.       Returns:  None
  1430.  
  1431.       Desc:     Places  a  bar menu  on  the screen  and  lets the  user  make a
  1432.                 selection from a list of choices.
  1433.  
  1434.                 'Selection' is  the name  of the integer  variable to  store the
  1435.                 user's choice in. 
  1436.  
  1437.                 'Len' is the minimum length of each bar.  This is usually set to
  1438.                 40.
  1439.  
  1440.                 'Start' is the selection number to start on when the bar menu is
  1441.                 first called. 
  1442.  
  1443.                 If 'removewin'  is non-zero, the  bar menu will be  removed from
  1444.                 the screen once the user makes a selection. 
  1445.  
  1446.                 If there are more than 10 selections in the menu, it will scroll
  1447.                 after  the  user  presses  the  down key  on  the  last  visible
  1448.                 selection.   The Page Up, Page Down, Home,  End, and Up and Down
  1449.                 arrow  keys  can be  used to  navigate  the menu.   If  <ESC> is
  1450.                 pressed,  'selection' is  set  to  0.   If  <ENTER> is  pressed,
  1451.                 'selection'  is set  to the  currently  highlighted choice,  the
  1452.  
  1453.                                                (Function reference continues) 25       SpeedSOFT Development                                                     
  1454.  
  1455.  
  1456.                 first being 1.
  1457.  
  1458.                 Choices for the barmenu are defined after the actual call.  When
  1459.                 the user moves  to a different selection, the  short description
  1460.                 that is specified (if any) will be shown.  
  1461.  
  1462.                 The bar menu  is automatically centered on the screen.  This can
  1463.                 be overridden with the 'At' command.
  1464.  
  1465.       Example:  BarMenu   Selection, 40, 1, 1
  1466.                 Begin Installation
  1467.                 :This option starts the installation.
  1468.                 Choose Installation Groups
  1469.                 :This option lets you choose which groups you want to 
  1470.                 : install.
  1471.                 Toggle Overwrite [Current: %overwrite%]
  1472.                 :Toggle overwrite without prompting.
  1473.            EndBarMenu
  1474.  
  1475.            Everything  starting  with  a  colon  AFTER  the  selection  will  be
  1476.            displayed when  the user  moves to that  selection.   The description
  1477.            will  be in  a window  that  starts on  the line  specified  with the
  1478.            function 'SetDescLine'.
  1479.  
  1480.            See the example in BARMENU.ZSL.
  1481.  
  1482.  
  1483.       BeginInstall                                                           Int
  1484.       --------------------------------------------
  1485.  
  1486.       Parms:    None
  1487.  
  1488.       Returns:  Escape Integer:     1 - The installation was un-interrupted
  1489.                                     0 - The user aborted the installation
  1490.  
  1491.       Desc:     Begins  the installation  process, unpacking  files  and copying
  1492.                 them to the destination disk.  Disk space  is checked before the
  1493.                 process begins and an error is issued if there is not enough.  
  1494.  
  1495.       Example:  BeginInstall
  1496.  
  1497.  
  1498.       ChDir                                                                  Int
  1499.       --------------------------------------------
  1500.  
  1501.       Parms:    ChDir <FORMAT dir>
  1502.  
  1503.       Returns:  Integer:  1   Changed to directory successfully
  1504.                                0     Couldn't   change  directory  (it  probably
  1505.                                doesn't exist).
  1506.  
  1507.       Desc:     Changes to the directory specified in 'dir'.
  1508.  
  1509.       Example:  ChDir "C:\\ZINSTALL"
  1510.  
  1511.  
  1512.                                                (Function reference continues)      26
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.                                                           Z/Install User's Guide
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  
  1531.  
  1532.  
  1533.  
  1534.  
  1535.  
  1536.  
  1537.  
  1538.  
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.                                                (Function reference continues) 27       SpeedSOFT Development                                                     
  1579.  
  1580.  
  1581.       CheckInstallOK                                                        None
  1582.       --------------------------------------------
  1583.  
  1584.       Parms:    None
  1585.  
  1586.       Returns:  None
  1587.  
  1588.       Desc:     Checks that the following conditions are met:
  1589.  
  1590.                 (a) the user is installing from a floppy drive, and
  1591.                 (b) there is enough space on the destination disk.
  1592.  
  1593.                 If the conditions stated  are not met, a  window will appear  on
  1594.                 the  screen explaining  the error  to the  user, and  a possible
  1595.                 solution to the problem.  The installation will then abort.
  1596.  
  1597.                 You  can set  whether or  not hard  disk source  installation is
  1598.                 allowed   with  SetAllowFixedSrc.  It's  a  good  idea  to  call
  1599.                 CheckInstallOK  AFTER  the  user  selects  the  groups  and  the
  1600.                 destination disk, and BEFORE calling BeginInstall.
  1601.  
  1602.       Example:  CheckInstallOK
  1603.  
  1604.  
  1605.       CloseFile                                                             None
  1606.       --------------------------------------------
  1607.  
  1608.       Parms:    None
  1609.  
  1610.       Returns:  None
  1611.  
  1612.       Desc:     Closes the file previously opened with OpenFile.
  1613.  
  1614.       Example:  OpenFile  "RUNME.BAT"
  1615.            WriteFile "CD\\" Rootdir
  1616.            WriteFile "ZINSTALL.EXE"
  1617.            CloseFile
  1618.  
  1619.       ClrScr                                                                None
  1620.       --------------------------------------------
  1621.  
  1622.       Parms:    None
  1623.  
  1624.       Returns:  None
  1625.  
  1626.       Desc:     Fills the text screen with the character and attribute specified
  1627.                 with the SetBackChar and SetBackColor functions.
  1628.  
  1629.       Example:  ClrScr
  1630.  
  1631.  
  1632.       Copy                                                                   Int
  1633.       --------------------------------------------
  1634.  
  1635.       Parms:    Copy <STR src>, <STR dest>
  1636.  
  1637.                                                (Function reference continues)      28
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.                                                           Z/Install User's Guide
  1645.  
  1646.  
  1647.       Returns:  Escape Integer:     1 - The copy succeeded
  1648.                                2 - The copy failed: not enough destination space
  1649.                                0 - User aborted copy
  1650.  
  1651.       Desc:     Copies  the file 'src' to 'dest'.  A  window is popped up on the
  1652.                 screen with  a graph to  show percentage completion.   Z/Install
  1653.                 tries to allocate  64k or memory for  the copy buffer.   If that
  1654.                 fails, it  keeps decreasing  the size  of the  buffer by  8k and
  1655.                 tries again until there is enough memory to allocate it.
  1656.  
  1657.       Example:  Copy "FILE1", "FILE2"
  1658.  
  1659.  
  1660.       Delete                                                                 Int
  1661.       --------------------------------------------
  1662.  
  1663.       Parms:    Delete <FORMAT filename>
  1664.  
  1665.       Returns:  Integer:  1 - File deleted OK
  1666.                           0 - File could not be deleted
  1667.  
  1668.       Desc:     Deletes the file 'filename' from the disk.  The file is  deleted
  1669.                 regardless  of its  attributes  (Hidden  and  System  files  are
  1670.                 deleted too).  'Filename' can contain wildcards.
  1671.  
  1672.       Example:  Delete "TEMP.FIL"
  1673.  
  1674.  
  1675.       Dialog                                                                 Int
  1676.       --------------------------------------------
  1677.  
  1678.       Parms:    Dialog <INT forcelen>, <INT keep>
  1679.  
  1680.       Returns:  Escape Integer:     1 - The user didn't press <ESí'(                                       Z/Install
  1681.                                      Version 1.0
  1682.  
  1683.                       (c) Copyright 1992  SpeedSOFT Development
  1684.                                  deleted too).  'Filename' can contain wildcards. later∞XFILES]∞X!      Example:  Delete "TEMP.FIL" put ∞Xon the∞Xon dis∞XP      Dialog                             C>
  1685.                                     0 - The user DID press <ESC>
  1686.  
  1687.       Desc:     Places a windowed dialog on the screen.   The dialog's style and
  1688.                 color are set with the 'SetDialog...'  functions.  If 'forcelen'
  1689.                 is  non-zero,  the  dialog  will  be  a  minimum  of  'forcelen'
  1690.                 characters wide.  Otherwise, it will be the width of the longest
  1691.                 line in the contents.  If 'keep' is non-zero, the dialog will be
  1692.                 put  up  on  the  screen  and  the  script  will  keep  running.
  1693.                 Otherwise, it  will wait  for the user  to hit  a key,  and then
  1694.                 remove  itself from  the screen.    The contents  of the  dialog
  1695.                 window follows  the call to  Dialog, and ends when  the compiler
  1696.                 encounters 'EndDialog'.  
  1697.  
  1698.                 If you want to display the contents of a variable in the dialog,
  1699.                 simply type  in the  name of the  variable, surrounded  with '%'
  1700.                 characters.  For example:
  1701.  
  1702.                 Dos version: %osmajor%.%osminor%
  1703.  
  1704.                 Z/Install allows input to  be received through a dialog,  simply
  1705.                 by placing:
  1706.  
  1707.                                                (Function reference continues) 29       SpeedSOFT Development                                                     
  1708.  
  1709.  
  1710.                 @EVariableName
  1711.  
  1712.                 in the  contents.  VariableName must  be a string variable.   If
  1713.                 input is received through the  dialog, it should be on the  last
  1714.                 line since each line in the dialog is displayed sequentially.
  1715.  
  1716.                 If you wish to center any line in the dialog, simply put '@C' at
  1717.                 the beginning of the line.
  1718.  
  1719.                 The dialog is automatically centered  on the screen. This can be
  1720.                 overridden with the 'At' command.  
  1721.  
  1722.       Example:  str mystring
  1723.  
  1724.                 Dialog 40, 0 
  1725.  
  1726.                      This is a 40 character wide dialog.
  1727.  
  1728.                      @CThis is centered.
  1729.                      Input something:
  1730.  
  1731.                      @Emystring
  1732.  
  1733.                 EndDialog
  1734.  
  1735.                 See the example in DIALOG.ZSL.
  1736.  
  1737.  
  1738.       DosCommand                                                             Int
  1739.       --------------------------------------------
  1740.  
  1741.       Parms:    DosCommand <FORMAT command>
  1742.  
  1743.       Returns:  Integer:  The DOS errorlevel return from 'command', OR
  1744.                 0 - 'command' was not found.
  1745.  
  1746.       Desc:     Shells to DOS  and performs the string in  'command'.  Z/Install
  1747.                 will search the DOS  PATH environment variable for  'command' if
  1748.                 it can't  find 'command' in  the current  directory.   Z/Install
  1749.                 will  be swapped to  EMS, XMS or  disk first, leaving  only a 2k
  1750.                 kernel in memory.  
  1751.  
  1752.       Example:  DosCommand "DIR /W"
  1753.  
  1754.  
  1755.       ElIf                                                                  None
  1756.       --------------------------------------------
  1757.  
  1758.       Parms:    ElIf <ANY Op1> <BOOL> <ANY Op2> 
  1759.  
  1760.       Returns:  None
  1761.  
  1762.       Desc:     If the result of the comparison from the last '..If..' statement
  1763.                 was false,  this comparison will  be evaluated.  Op1  must be of
  1764.                 the same data type  as Op2.  If the comparison is  true, all the
  1765.  
  1766.                                                (Function reference continues)      30
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.                                                           Z/Install User's Guide
  1774.  
  1775.  
  1776.                 statements up to  the next '..If..' statement  will be executed.
  1777.                 Otherwise, they will be  skipped and the script will jump to the
  1778.                 next '..If..' statement.
  1779.  
  1780.       Example:  See 'If'
  1781.  
  1782.  
  1783.       Else                                                                  None
  1784.       --------------------------------------------
  1785.  
  1786.       Parms:    None
  1787.  
  1788.       Returns:  None
  1789.  
  1790.       Desc:     If all of the other comparisons  in an 'If' loop fail, the  ones
  1791.                 after  the 'Else' statement  and up until  the 'EndIf' statement
  1792.                 will be executed, if any.  There  can be only one 'Else' in each
  1793.                 'If' loop.
  1794.  
  1795.       Example:  See 'If'
  1796.  
  1797.  
  1798.       EndIf                                                                None 
  1799.       --------------------------------------------
  1800.  
  1801.       Parms:    None
  1802.  
  1803.       Returns:  None
  1804.  
  1805.       Desc:     Ends an 'If' loop.
  1806.  
  1807.       Example:  See 'If'
  1808.  
  1809.  
  1810.       ExitScript                                                            None
  1811.       --------------------------------------------
  1812.  
  1813.       Parms:    None
  1814.  
  1815.       Returns:  None
  1816.  
  1817.       Desc:     Exits the installation  program.  If 'SetRestoreDOS'  is ON, the
  1818.                 original  DOS  screen  is  restored, and  the  message  set with
  1819.                 SetExitMsg  is displayed.    Otherwise,  the  script  will  exit
  1820.                 without touching the screen.
  1821.  
  1822.       Example:  ExitScript
  1823.  
  1824.  
  1825.       FileType                                                               Int
  1826.       --------------------------------------------
  1827.  
  1828.       Parms:    FileType <FORMAT filename>
  1829.  
  1830.       Returns:  Integer:  1 - The file is a DOS file
  1831.  
  1832.                                                (Function reference continues) 31       SpeedSOFT Development                                                     
  1833.  
  1834.  
  1835.                 2 - The file is a directory
  1836.                 0 - The file does not exist
  1837.  
  1838.       Desc:     Checks for  the existence of  'filename' and returns one  of the
  1839.                 integers above, depending on the type of 'filename'.
  1840.  
  1841.       Example:  int x = FileType "C:\\DOS"
  1842.  
  1843.  
  1844.       GetChoice                                                              Str
  1845.       --------------------------------------------
  1846.  
  1847.       Parms:    GetChoice <STR choices>
  1848.  
  1849.       Returns:  String
  1850.  
  1851.       Desc:     Waits for the  user to press one  of the keys in  'choices'.  If
  1852.                 'choices' is blank, it waits for  any key.  If the user  presses
  1853.                 <ESC>, 'GetChoice' will return a  blank string ("") or Z/Install
  1854.                 will exit, depending on the 'SetEscapeType' function.
  1855.  
  1856.       Example:  str yesorno = GetChoice "YN"
  1857.  
  1858.                 If yesorno = "Y"
  1859.                      print     "You typed Y\n"
  1860.                 Else
  1861.                      print     "You typed N\n"
  1862.                 EndIf
  1863.  
  1864.  
  1865.       GetCommandLine                                                         Str
  1866.       --------------------------------------------
  1867.  
  1868.       Params:   GetCommandLine <INT number>
  1869.  
  1870.       Returns:  String 
  1871.  
  1872.       Desc:     Returns  a  string   containing  command-line  argument   number
  1873.                 'number'.    If  there  are  less  command-line  arguments  than
  1874.                 'number',  it  returns  an  empty  string  ("").    Command-line
  1875.                 argument 0 is the installation executable's path and filename.
  1876.  
  1877.       Example:  str arg
  1878.  
  1879.                 arg = GetCommandLine 1
  1880.  
  1881.                 print "Command line argument number 1:", arg, "\n"
  1882.  
  1883.  
  1884.       GetDir                                                                 Str
  1885.       --------------------------------------------
  1886.  
  1887.       Parms:    None
  1888.  
  1889.       Returns:  A string containing the current directory.
  1890.  
  1891.                                                (Function reference continues)      32
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.                                                           Z/Install User's Guide
  1899.  
  1900.  
  1901.       Desc:     GetDir returns  a string containing the current drive/directory,
  1902.                 in the format:
  1903.  
  1904.                 C:\DOS
  1905.                 C:\WINDOWS\SYSTEM
  1906.  
  1907.       Example:  str curdir = GetDir
  1908.  
  1909.  
  1910.       GetDisk                                                                Str
  1911.       --------------------------------------------
  1912.  
  1913.       Parms:    None
  1914.  
  1915.       Returns:  The current drive, as a string.
  1916.  
  1917.       Desc:     GetDisk returns the current drive as single-character string, ie
  1918.                 "C".
  1919.  
  1920.       Example:  str curdrive = GetDisk
  1921.                 print "The current disk drive is ", curdrive, ":\n"
  1922.  
  1923.  
  1924.  
  1925.  
  1926.  
  1927.  
  1928.  
  1929.  
  1930.  
  1931.  
  1932.  
  1933.  
  1934.  
  1935.  
  1936.  
  1937.  
  1938.  
  1939.  
  1940.  
  1941.  
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.  
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.                                                (Function reference continues) 33       SpeedSOFT Development                                                     
  1958.  
  1959.  
  1960.       GetInstallationDrive                                                   Int
  1961.       --------------------------------------------
  1962.  
  1963.       Parms:    None
  1964.  
  1965.       Returns:  Escape Integer:     1 - The user selected a drive
  1966.                      0 - The user pressed <ESC>
  1967.  
  1968.       Desc:     Displays a bar menu  enabling the user to choose which  drive to
  1969.                 install to  (the destination disk).   Once the  user has  made a
  1970.                 selection, the global string  variable 'Instdrv' will be  set to
  1971.                 the chosen drive letter.  The bar menu is automatically centered
  1972.                 on the screen;  This can be overridden with the 'At' command.
  1973.  
  1974.       Example:  GetInstallationDrive @(0,11)       ; Get installation drive, 
  1975.                                                    ; barmenu starts on line 11.
  1976.  
  1977.  
  1978.       GetInstallGroups                                                       Int
  1979.       --------------------------------------------
  1980.  
  1981.       Parms:    None
  1982.  
  1983.       Returns:  Escape Integer:     1 - The user didn't abort
  1984.                      0 - The user pressed <ESC>
  1985.  
  1986.       Desc:     Displays a bar menu on the screen and lets the user choose which
  1987.                 groups he/she wants to  install.  The groups are  toggled on and
  1988.                 off with the <ENTER>  key.  The last selection in  the menu will
  1989.                 be 'Continue  Installation'.  Once  the user  selects this,  the
  1990.                 script will continue.  The bar menu is automatically centered on
  1991.                 the screen.  This can be overridden with the 'At' command.
  1992.  
  1993.       Example:  GetInstallGroups
  1994.  
  1995.  
  1996.       GetVolumeLabel                                                         Str
  1997.       --------------------------------------------
  1998.  
  1999.       Parms:    None
  2000.  
  2001.       Returns:  A string containing the volume label.
  2002.  
  2003.       Desc:     GetVolumeLabel returns a  string that contains the  volume label
  2004.                 for the current drive.  
  2005.  
  2006.       Example:  str vol = GetVolumeLabel
  2007.  
  2008.  
  2009.  
  2010.  
  2011.  
  2012.  
  2013.  
  2014.  
  2015.  
  2016.                                                (Function reference continues)      34
  2017.  
  2018.  
  2019.  
  2020.  
  2021.  
  2022.  
  2023.                                                           Z/Install User's Guide
  2024.  
  2025.  
  2026.       GoSub                                                                 None
  2027.       --------------------------------------------
  2028.  
  2029.       Params:   GoSub <LABEL label>
  2030.  
  2031.       Returns:  None
  2032.  
  2033.       Desc:     Pushes the current script file position on the 'Gosub Stack' and
  2034.                 jumps to the  line in the script  file after the declaration  of
  2035.                 'label'.  The function 'Return' can then be used to jump back to
  2036.                 the line after the 'GoSub' call.
  2037.  
  2038.       Example:  Str printstr
  2039.  
  2040.            printstr = "Hello, world!\n"
  2041.            GoSub Printit
  2042.            printstr = "Goodbye, world!\n"
  2043.            GoSub Printit
  2044.            ExitScript
  2045.  
  2046.            Label Printit  ; Declare the label that we jump to
  2047.            print printstr ; Print the message
  2048.            Return         ; Jump back.
  2049.  
  2050.  
  2051.       Goto                                                                  None
  2052.       --------------------------------------------
  2053.  
  2054.       Parms:    Goto <LABEL label>
  2055.  
  2056.       Returns:  None
  2057.  
  2058.       Desc:     Jumps to the line after the declaration of <label> in the script
  2059.                 file.  If the Goto statement is inside of an 'If' loop, the 'If'
  2060.                 stack will be reset before the jump is made.
  2061.  
  2062.       Example:  If    VgaEga = 1
  2063.                  Goto InstallVGA
  2064.            Endif
  2065.  
  2066.  
  2067.       If                                                                    None
  2068.       --------------------------------------------
  2069.  
  2070.       Parms:    If <ANY Op1> <BOOL> <ANY Op2>
  2071.  
  2072.       Returns:  None
  2073.  
  2074.       Desc:     Performs an 'If'  comparison and begins  a new 'If' level.   Op1
  2075.                 and Op2  must be the same data type.  If the comparison is true,
  2076.                 all  statements  until  the  next  '..If..'  statement  will  be
  2077.                 executed.  Otherwise, they will be ignored.
  2078.  
  2079.            'Op1' is the expression to compare.
  2080.  
  2081.  
  2082.                                                (Function reference continues) 35       SpeedSOFT Development                                                     
  2083.  
  2084.  
  2085.            'bool' can be one of the following:
  2086.  
  2087.                 =    Equal to.  The comparison will be true if 'Op1' is equal to
  2088.                      'Op2'.  Strings are compared character by character until a
  2089.                      difference is found, and integers are compared directly.
  2090.  
  2091.                 >    Greater than.
  2092.                 <    Less than.
  2093.                 >=   Greater than or equal to.
  2094.                 <=   Less than or equal to.
  2095.                 !=   Not equal to.
  2096.  
  2097.            'Op2' is the expression to compare 'Op1' with.
  2098.  
  2099.       Example:  str name1 = "George"
  2100.            str name2 = "Mary"
  2101.  
  2102.            ; The following IF statement will be true, because 'G' is  a lesser ;
  2103.            ASCII value than 'M'.
  2104.  
  2105.            If   name1 < name2
  2106.                 print "\"George\" has a lesser ASCII value than \"Mary\"."
  2107.            EndIf
  2108.  
  2109.  
  2110.       Int                                                                   None
  2111.       --------------------------------------------
  2112.  
  2113.       Parms:    Int <name> [= value]
  2114.  
  2115.       Returns:  None
  2116.  
  2117.       Desc:     Declares an integer and calls  it 'name'.  'Name' cannot contain
  2118.                 spaces, and  must  begin with  an alphabetical  character or  an
  2119.                 underscore  (_).  Integers can be initialized  to a value, as in
  2120.                 the example below:
  2121.  
  2122.       Example:  Int My_int = 5
  2123.  
  2124.  
  2125.  
  2126.  
  2127.  
  2128.  
  2129.  
  2130.  
  2131.  
  2132.  
  2133.  
  2134.  
  2135.  
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.                                                (Function reference continues)      36
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.                                                           Z/Install User's Guide
  2149.  
  2150.  
  2151.       Label                                                                 None
  2152.       --------------------------------------------
  2153.  
  2154.       Parms:    Label <labelname>
  2155.  
  2156.       Returns:  None
  2157.  
  2158.       Desc:     Declares a  label for GOTO/GOSUB jumps.   When you call  a Go...
  2159.                 function and pass  it the label you define here, it will jump to
  2160.                 the line  after the  label command.   Labels cannot  be declared
  2161.                 inside an 'If' loop.
  2162.  
  2163.       Example:  Label loop
  2164.                 ...
  2165.            Goto loop
  2166.  
  2167.  
  2168.       MarkFilesTime                                                         None
  2169.       --------------------------------------------
  2170.  
  2171.       Params:   MarkFilesTime <INT hour>, <INT minute>, <INT second>
  2172.  
  2173.       Returns:  None
  2174.  
  2175.       Desc:     Marks all files written to  the destination disk with this time.
  2176.  
  2177.  
  2178.       Example:  MarkFilesTime 1, 0, 0
  2179.  
  2180.  
  2181.       MarkFilesDate                                                         None
  2182.       --------------------------------------------
  2183.  
  2184.       Params:   MarkFilesDate <INT month>, <INT day>, <INT year>
  2185.  
  2186.       Returns:  None
  2187.  
  2188.       Desc:     Marks all files written to the destination disk with this date.
  2189.  
  2190.       Example:  MarkFilesDate 1, 14, 92
  2191.  
  2192.  
  2193.       MkDir                                                                  Int
  2194.       --------------------------------------------
  2195.  
  2196.       Parms:    MkDir <FORMAT name>
  2197.  
  2198.       Returns:  Integer:  0 - Operation failed (couldn't MkDir)
  2199.                 1 - Operation succeeded
  2200.  
  2201.       Desc:     MkDir attempts  to make  the directory 'name'.   If it  can't (a
  2202.                 file  already  exists  with  the  same  name),   it  returns  0.
  2203.                 Otherwise, it returns 1.
  2204.  
  2205.       Example:  int ok = MkDir "TEMP"
  2206.  
  2207.                                                (Function reference continues) 37       SpeedSOFT Development                                                     
  2208.  
  2209.  
  2210.  
  2211.       ModPath                                                               None
  2212.       --------------------------------------------
  2213.  
  2214.       Parms:    ModPath <FORMAT path>
  2215.  
  2216.       Returns:  None
  2217.  
  2218.       Desc:     Modifies the PATH statement in AUTOEXEC.BAT.  It adds the string
  2219.                 'path' if it's not already in the PATH= statement.  If  there is
  2220.                 no path statement, it appends one to the end of the file.
  2221.  
  2222.       Example:  ModPath "C:\\ZINSTALL"
  2223.  
  2224.  
  2225.       NetworkType                                                            Int
  2226.       --------------------------------------------
  2227.  
  2228.       Parms:    None
  2229.  
  2230.       Returns:  Integer:  0 - No network installed
  2231.                 1 - Novell NetWare installed
  2232.                 2 - NETBIOS network (Lantastic, etc.) installed
  2233.  
  2234.       Desc:     Returns an integer corresponding to the type of network (if any)
  2235.                 installed.  Note that this  function will only work correctly if
  2236.                 the  network  shell  (NetWare) or  the  redirector  (NETBIOS) is
  2237.                 installed.
  2238.  
  2239.       Example:  int isnet = NetworkType
  2240.  
  2241.            If isnet = 0
  2242.                goto InstallNoNetwork
  2243.            ElIf isnet = 1
  2244.                goto InstallNetware
  2245.            Else
  2246.                goto InstallNETBIOS
  2247.            Endif
  2248.  
  2249.  
  2250.  
  2251.  
  2252.  
  2253.  
  2254.  
  2255.  
  2256.  
  2257.  
  2258.  
  2259.  
  2260.  
  2261.  
  2262.  
  2263.  
  2264.  
  2265.  
  2266.                                                (Function reference continues)      38
  2267.  
  2268.  
  2269.  
  2270.  
  2271.  
  2272.  
  2273.                                                           Z/Install User's Guide
  2274.  
  2275.  
  2276.       OpenFile                                                              None
  2277.       --------------------------------------------
  2278.  
  2279.       Parms:    OpenFile <FORMAT filename>
  2280.  
  2281.       Returns:  None
  2282.  
  2283.       Desc:     Opens the  file 'filename' for appending.   It creates it  if it
  2284.                 doesn't  already   exist.     The   functions  'WriteFile'   and
  2285.                 'CloseFile' can then be used to write to the file and  close it,
  2286.                 respectively.  Note that only one file can be open at a time.  
  2287.  
  2288.       Example:  See CloseFile
  2289.  
  2290.  
  2291.       Pause                                                                 None
  2292.       --------------------------------------------
  2293.  
  2294.       Parms:    Pause <INT nsec>
  2295.  
  2296.       Returns:  None
  2297.  
  2298.       Desc:     Pauses for 'nsec' seconds.  'Nsec' can be no more than 5.
  2299.  
  2300.       Example:  Pause 2
  2301.  
  2302.  
  2303.       Print                                                                 None
  2304.       --------------------------------------------
  2305.  
  2306.       Params:   Print <FORMAT string>
  2307.  
  2308.       Returns:  None
  2309.  
  2310.       Desc:     Prints 'string' to DOS standard output.
  2311.  
  2312.       Example:  Print "Hello, world!\n"
  2313.  
  2314.  
  2315.       ReBoot                                                                None
  2316.       --------------------------------------------
  2317.  
  2318.       Parms:    None
  2319.  
  2320.       Returns:  None
  2321.  
  2322.       Desc:     Performs a warm boot of the computer. 
  2323.  
  2324.       Example:  ReBoot
  2325.  
  2326.  
  2327.       RepeatRate                                                            None
  2328.       --------------------------------------------
  2329.  
  2330.       Parms:    RepeatRate <INT cps>
  2331.  
  2332.                                                (Function reference continues) 39       SpeedSOFT Development                                                     
  2333.  
  2334.  
  2335.       Returns:  None
  2336.  
  2337.       Desc:     Sets the  keyboard repeat rate  to 'cps'  characters per  second
  2338.       (maximum 30).
  2339.  
  2340.       Example:  RepeatRate 25
  2341.  
  2342.  
  2343.       RestoreScreen                                                         None
  2344.       --------------------------------------------
  2345.  
  2346.       Parms:    None
  2347.  
  2348.       Returns:  None
  2349.  
  2350.       Desc:     Restores  the screen previously saved with SaveScreen.  Warning:
  2351.                 If SaveScreen  is not called prior to  RestoreScreen, the screen
  2352.                 will be filled with garbage. 
  2353.  
  2354.       Example:  SaveScreen
  2355.  
  2356.            Dialog 40, 1        ; Dialog on screen, keep it there.
  2357.  
  2358.                 @CChoose destination disk drive:
  2359.  
  2360.            End_Dialog
  2361.  
  2362.            GetInstallationDrive
  2363.            RestoreScreen
  2364.  
  2365.  
  2366.       Return                                                                None
  2367.       --------------------------------------------
  2368.  
  2369.       Params:   None
  2370.  
  2371.       Returns:  None
  2372.  
  2373.       Desc:     'Return' will jump to the line after the last 'GoSub' call.  
  2374.  
  2375.       Example:  See 'GoSub'
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.  
  2384.  
  2385.  
  2386.  
  2387.  
  2388.  
  2389.  
  2390.  
  2391.                                                (Function reference continues)      40
  2392.  
  2393.  
  2394.  
  2395.  
  2396.  
  2397.  
  2398.                                                           Z/Install User's Guide
  2399.  
  2400.  
  2401.       RmDir                                                                  Int
  2402.       --------------------------------------------
  2403.  
  2404.       Parms:    RmDir <FORMAT dirname>
  2405.  
  2406.       Returns:  Integer:  0 - Couldn't  remove directory. This means  that there
  2407.                           are still files in the   directory,   or    that   the
  2408.                           directory doesn't exist.
  2409.                 1 - Removed directory OK.
  2410.  
  2411.       Desc:     RmDir attempts to remove the directory specified in 'dirname'.
  2412.  
  2413.       Example:  int ok = RmDir "TEMP"
  2414.  
  2415.  
  2416.       SaveScreen                                                            None
  2417.       --------------------------------------------
  2418.  
  2419.       Parms:    None
  2420.  
  2421.       Returns:  None
  2422.  
  2423.       Desc:     Saves the screen for later restoration with RestoreScreen.
  2424.  
  2425.       Example:  See RestoreScreen
  2426.  
  2427.  
  2428.       SetAllowFixedSrc                                                      None
  2429.       --------------------------------------------
  2430.  
  2431.       Parms:    SetAllowFixedSrc <ONOFF>
  2432.  
  2433.       Returns:  None
  2434.  
  2435.       Desc:     Specifies whether or not the user may install FROM a fixed disk.
  2436.                 Even if the  user uses SUBST or ASSIGN, Z/Install  will catch it
  2437.                 and   not  let   them   install.     This   gets  checked   when
  2438.                 'CheckInstallOK' is called. 
  2439.  
  2440.       Example:  SetAllowFixedSrc Off     ; Don't allow fixed source disks
  2441.            CheckInstallOK
  2442.  
  2443.       SetBuffers                                                            None
  2444.       --------------------------------------------
  2445.  
  2446.       Parms:    SetBuffers <INT buffers>
  2447.  
  2448.       Returns:  None
  2449.  
  2450.       Desc:     Modifies CONFIG.SYS to  include the line "BUFFERS=n", where n is
  2451.                 the number specified in 'buffers'.   If CONFIG.SYS already has a
  2452.                 "BUFFERS=" line,  it will  be updated to  'buffers' ONLY  if the
  2453.                 current number is smaller than 'buffers'. 
  2454.  
  2455.       Example:  SetBuffers 20
  2456.  
  2457.                                                (Function reference continues) 41       SpeedSOFT Development                                                     
  2458.  
  2459.  
  2460.  
  2461.       SetDescLine                                                           None
  2462.       --------------------------------------------
  2463.  
  2464.       Parms:    SetDescLine <INT line>
  2465.  
  2466.       Returns:  None
  2467.  
  2468.       Desc:     Sets the starting line  for the description window when  BarMenu
  2469.                 is called. 'line' may be from 1 to 20.
  2470.  
  2471.       Example:  SetDescLine 17
  2472.  
  2473.  
  2474.       SetDisk                                                                Int
  2475.       --------------------------------------------
  2476.  
  2477.       Params:   SetDisk <STR disk>
  2478.  
  2479.       Returns:  Integer:  0 - Couldn't change disk
  2480.                 1 - Changed disk OK.
  2481.  
  2482.       Desc:     Sets the current  disk drive.  It  will only take notice  of the
  2483.                 first character in 'Disk'.  
  2484.       Example:  SetDisk InstDrv     ; Change to the destination disk drive.
  2485.  
  2486.  
  2487.       SetEnv                                                                None
  2488.       --------------------------------------------
  2489.  
  2490.       Parms:    SetEnv <FORMAT envstring>
  2491.  
  2492.       Returns:  None
  2493.  
  2494.       Desc:     Modifies  AUTOEXEC.BAT  to  include   the  environment  variable
  2495.                 envstring.  envstring should be in the format:
  2496.  
  2497.                 "ENVVAR=ENVSTRING"
  2498.  
  2499.            If AUTOEXEC.BAT  already has a  "SET" command with the  same variable
  2500.            name as specifed in 'envstring', it will be updated.
  2501.  
  2502.       Example:  SetEnv "ZINSTALL=C:\\ZINSTALL"
  2503.  
  2504.       SetEscapeType                                                         None
  2505.       --------------------------------------------
  2506.  
  2507.       Params:   SetEscapeType <INT type>
  2508.  
  2509.       Returns:  None
  2510.  
  2511.       Desc:     Sets  the way  in which  Z/Install handles  the <ESC>  key.   If
  2512.                 'type' is  zero, Z/Install will intercept all  <ESC> key presses
  2513.                 and ask the user if they  want to exit.  If 'type'  is non-zero,
  2514.                 any funtion  that returns an  'Escape Integer' will return  0 if
  2515.  
  2516.                                                (Function reference continues)      42
  2517.  
  2518.  
  2519.  
  2520.  
  2521.  
  2522.  
  2523.                                                           Z/Install User's Guide
  2524.  
  2525.  
  2526.                 <ESC> is pressed.
  2527.  
  2528.       Example:  SetEscapeType 0          ; Let Z/Install handle ESC key presses.
  2529.  
  2530.  
  2531.       SetExitMessage                                                        None
  2532.       --------------------------------------------
  2533.  
  2534.       Parms:    SetExitMessage <FORMAT message>
  2535.  
  2536.       Returns:  None
  2537.  
  2538.       Desc:     Sets the message that is  displayed to the user after ExitScript
  2539.                 is called.
  2540.  
  2541.       Example:  SetExitMessage "Contact us at (800) 555-1212"
  2542.  
  2543.  
  2544.       SetFileGroup                                                          None
  2545.       --------------------------------------------
  2546.  
  2547.       Parms:    SetFileGroup <INT group>, ONOFF 
  2548.  
  2549.       Returns:  None
  2550.  
  2551.       Desc:     Manually sets file group 'group' on or off.
  2552.  
  2553.       Example:  SetFileGroup 1 OFF  ; Don't install group 1.
  2554.  
  2555.        
  2556.       SetFiles                                                              None
  2557.       --------------------------------------------
  2558.  
  2559.       Parms:    SetFiles <INT numfiles>
  2560.  
  2561.       Returns:  None
  2562.  
  2563.       Desc:     Modifies CONFIG.SYS to  include the line  "FILES=n", where n  is
  2564.                 the number specified in 'numfiles'.  If CONFIG.SYS already has a
  2565.                 "FILES="  line, it  will be  updated to  'numfiles' ONLY  if the
  2566.                 current number is smaller than 'numfiles'.
  2567.  
  2568.       Example:  SetFiles 50         ; Set FILES=50 in config.sys
  2569.  
  2570.  
  2571.       SetInputTplate                                                        None
  2572.       --------------------------------------------
  2573.  
  2574.       Parms:    SetInputTplate <STR tplate>
  2575.  
  2576.       Returns:  None
  2577.  
  2578.       Desc:     Sets the input template  for the edit function in dialogs.   The
  2579.                 template  is a  series of  picture control characters  and input
  2580.                 characters.  The input characters are the only ones that receive
  2581.  
  2582.                                                (Function reference continues) 43       SpeedSOFT Development                                                     
  2583.  
  2584.  
  2585.                 input. They are:
  2586.  
  2587.                 A - Any alphabetical character
  2588.                 * - Any character at all
  2589.                 F - Only filename characters
  2590.                 P - Filename and path characters
  2591.                 # - Any digit, 0 to 9
  2592.                 @ - Digits and alpha characters
  2593.                 ? - Only 'Y' or 'N'
  2594.  
  2595.       Example:  SetInputTplate "(###) ### ####"
  2596.  
  2597.            See more examples in EDIT.ZSL.
  2598.  
  2599.  
  2600.       SetRestoreDOS                                                         None
  2601.       --------------------------------------------
  2602.  
  2603.       Params:   SetRestoreDOS <ONOFF>
  2604.  
  2605.       Returns:  None
  2606.  
  2607.       Desc:     Sets whether  or not Z/Install  will restore the DOS  screen and
  2608.                 cursor location when the script finishes running.
  2609.  
  2610.       Example:  SetRestoreDOS Off
  2611.  
  2612.  
  2613.       Str                                                                   None
  2614.       --------------------------------------------
  2615.  
  2616.       Parms:    Str <name> [=value]
  2617.  
  2618.       Returns:  None
  2619.  
  2620.       Desc:     Declares an integer and calls  it 'name'.  'Name' cannot contain
  2621.                 spaces,  and must  begin with  an alphabetical  character or  an
  2622.                 underscore (_).   Strings can be  initialized to a value,  as in
  2623.                 the example below:
  2624.  
  2625.       Example:  Str My_str = "Hello, World!\n"
  2626.  
  2627.  
  2628.       UseBlink                                                              None
  2629.       --------------------------------------------
  2630.  
  2631.       Parms:    None
  2632.  
  2633.       Returns:  None
  2634.  
  2635.       Desc:     Turns   off  high intensity  background   colors  and  turns  on
  2636.       blinking.
  2637.  
  2638.       Example:  UseBlink
  2639.  
  2640.  
  2641.                                                (Function reference continues)      44
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  
  2647.  
  2648.                                                           Z/Install User's Guide
  2649.  
  2650.  
  2651.       UseHighIntensityBGColors                                              None
  2652.       --------------------------------------------
  2653.  
  2654.       Parms:    None
  2655.  
  2656.       Returns:  None
  2657.  
  2658.       Desc:     Turns  on  high intensity  background   colors  and  turns   off
  2659.                 blinking.  This is the complement of UseBlink.
  2660.  
  2661.       Example:  UseHighIntensityBGColors
  2662.  
  2663.  
  2664.       ViewFile                                                              None
  2665.       --------------------------------------------
  2666.  
  2667.       Parms:    ViewFile <FORMAT filename>
  2668.  
  2669.       Returns:  None
  2670.  
  2671.       Desc:     Lets  the user  browse  the  file 'filename',  and  print it  if
  2672.                 required.   The user can use Page Up,  Page Down, Home, End, Up,
  2673.                 Down, Left and Right to navigate.   By hitting 'G', the user can
  2674.                 go to any line in the file.  
  2675.  
  2676.       Example:  ViewFile Instdrv, ":", Rootdir, "\\README.DOC"
  2677.  
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  
  2707.                                                                               45       SpeedSOFT Development                                                     
  2708.  
  2709.  
  2710.       WriteScreen                                                           None
  2711.       --------------------------------------------
  2712.  
  2713.       Params:   WriteScreen <COLOR color>, <INT col>, <INT row>, <FORMAT str>
  2714.  
  2715.       Returns:  None
  2716.  
  2717.       Desc:     Writes 'str' to the text screen  at the position 'col' and 'row'
  2718.                 using  the color 'color'.   'Col' can be from  0 to 79 and 'row'
  2719.                 can be from 1  to 25.  If 'col' is zero,  'str' will be centered
  2720.                 horizontally.  
  2721.  
  2722.       Example:  WriteScreen BlackOnWhite, 0, 1, " Z/Install Installation Program
  2723.                 "
  2724.  
  2725.  
  2726.  
  2727.  
  2728.  
  2729.  
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735.  
  2736.  
  2737.  
  2738.  
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.       46                                                           Z/Install User's Guide
  2767.  
  2768.  
  2769.                                       Appendix B
  2770.  
  2771.       Z/Install  has four  types of  information  sections in  its script  file.
  2772.       Their uses  are discussed in Chapter 2.8.   This Appendix describes how to
  2773.       write them.  The  keyword [END] must appear at the end  of each section to
  2774.       tell the compiler that the section is finished.  
  2775.  
  2776.  
  2777.       B.1 - The [GROUPS] Section
  2778.       --------------------------------------------
  2779.  
  2780.       This information section is optional.  Its format is as follows:
  2781.  
  2782.       Group Number:Group Name:Install default [1/0]
  2783.  
  2784.       Example:
  2785.  
  2786.       [GROUPS]
  2787.       1:Main Program:1
  2788.       2:Spellchecker:0
  2789.       3:Thesaurus:0
  2790.       4:Printer Program:1
  2791.       [END]
  2792.  
  2793.       If this  section is not  in the  script file, the  installation executable
  2794.       will automatically install all files.
  2795.  
  2796.  
  2797.       B.2 - The [FILES] Section
  2798.       --------------------------------------------
  2799.  
  2800.       This information section is mandatory.  Its format is discussed in Chapter
  2801.       4.1
  2802.  
  2803.  
  2804.       B.3 - The [PATHS] Section
  2805.       --------------------------------------------
  2806.  
  2807.       This information section is mandatory.  Its format is as follows:
  2808.  
  2809.       Path Number:Pathname
  2810.  
  2811.       Example:
  2812.  
  2813.       [PATHS]
  2814.       0:\ZINSTALL
  2815.       1:\DOCS
  2816.       2:\OPTDIST
  2817.       3:\ZPACK
  2818.       4:\SAMPLES
  2819.       [END]
  2820.       Paths 1 and  up will be subdirectories  from Path 0.  It  is acceptable to
  2821.       have multiple subdirectories, such as:
  2822.  
  2823.       [PATHS]
  2824.  
  2825.                                                                               47       SpeedSOFT Development                                                     
  2826.  
  2827.  
  2828.       0:\ZINSTALL
  2829.       1:\DOCS\ORDER
  2830.       2:\DOCS\MAIN
  2831.       etc...
  2832.       [END]
  2833.  
  2834.       Path 0 is accessible with the string variable 'Rootdir'.  This is a useful
  2835.       festure  when  the user  needs to  be  prompted for  the directory  on the
  2836.       destination drive that the application will be installed to.
  2837.  
  2838.  
  2839.       B.4 - The [DISKS] Section
  2840.       --------------------------------------------
  2841.  
  2842.       This information section is mandatory.  Its format is as follows:
  2843.  
  2844.       Disk Number:Disk Label:Disk Description
  2845.  
  2846.       Example:
  2847.  
  2848.       [DISKS]
  2849.       1:ZINST001:Z/Install Disk 1
  2850.       2:ZINST002:Z/Install Disk 2
  2851.       [END]
  2852.  
  2853.       When the user is prompted to insert  another disk, the Disk Description is
  2854.       used to identify the disk.
  2855.  
  2856.       Note:     If  you used  OPTDist, you  MUST  use the  [DISKS] section  that
  2857.                 OPTDist writes. Otherwise, the order of the disks will get mixed
  2858.                 around and the installation will most likely fail.
  2859.  
  2860.  
  2861.  
  2862.  
  2863.  
  2864.  
  2865.  
  2866.  
  2867.  
  2868.  
  2869.  
  2870.  
  2871.  
  2872.  
  2873.  
  2874.  
  2875.  
  2876.  
  2877.  
  2878.  
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884.       48                                                           Z/Install User's Guide
  2885.  
  2886.  
  2887.                                       Appendix C
  2888.  
  2889.       This is an appendix of the  error messages that can appear when  compiling
  2890.       scripts.
  2891.  
  2892.  
  2893.       Invalid number of parameters in call to 'function'
  2894.       --------------------------------------------
  2895.  
  2896.            'Function' requires more parameters than you passed it.   Look up the
  2897.            function in the reference and check your parameters.
  2898.  
  2899.  
  2900.       Type mismatch in parameter 'number' in call to 'function'
  2901.       --------------------------------------------
  2902.  
  2903.            Argument  'number' in  your call  to  'function' is  the wrong  type.
  2904.            Example:   You passed  the function  an integer  when  it required  a
  2905.            string.   Look  up  the  function in  the  reference  and check  your
  2906.            parameters.
  2907.  
  2908.  
  2909.       Unexpected EOF encountered in 'function'
  2910.       --------------------------------------------
  2911.  
  2912.            The compiler encountered the end  of your script file when it  wasn't
  2913.            expecting it.   This error can occur when the compiler is parsing one
  2914.            of the following functions:
  2915.  
  2916.                 Dialog
  2917.                 BarMenu
  2918.                 Any of the [INFORMATION] sections.
  2919.  
  2920.            Solution: Check to see that your function has the correct terminating
  2921.            keyword.      (For  example,   "Dialog"'s   terminating   keyword  is
  2922.            'EndDialog'.
  2923.  
  2924.  
  2925.       Cannot start installation here - 'function' not defined
  2926.       --------------------------------------------
  2927.  
  2928.            'BeginInstall' was  called before 'function'  was called.   Make sure
  2929.            'function' is called at least once before  'BeginInstall' and compile
  2930.            again.
  2931.  
  2932.  
  2933.  
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.  
  2943.                                                                               49       SpeedSOFT Development                                                     
  2944.  
  2945.  
  2946.       Undefined symbol 'symbol'
  2947.       --------------------------------------------
  2948.  
  2949.            The  compiler encountered a  variable or goto symbol  that it did not
  2950.            recognise.  It was probably misspelled.
  2951.  
  2952.  
  2953.       Value out of range in parameter 'number' in call to 'function'
  2954.       --------------------------------------------
  2955.  
  2956.            The value  that  was passed  in  parameter 'number'  in  the call  to
  2957.            'function' was out of range.  Look up 'function' in the reference and
  2958.            check the parameters.
  2959.  
  2960.  
  2961.       Duplicate definition for 'symbol'
  2962.       --------------------------------------------
  2963.  
  2964.            'Symbol' was declared more than once.  This happens if a  variable is
  2965.            declared (See 'Int'  and 'Str' in the function  reference), and later
  2966.            in  the script  another  variable  is declared  with  the same  name.
  2967.            Remember that ZSL is case-insensitive.
  2968.  
  2969.  
  2970.       Invalid ColorString format for function 'function'
  2971.       --------------------------------------------
  2972.  
  2973.            The  ColorString  that   was  passed  to  'function'   was  formatted
  2974.            incorrectly.   See  Chapter  2.8  for information  on  the format  of
  2975.            ColorStrings.
  2976.  
  2977.  
  2978.       Function 'function' called outside of 'if' loop
  2979.       --------------------------------------------
  2980.  
  2981.            The function 'Else', 'Elif' or 'Endif'  was called outside of an 'If'
  2982.            loop.  These functions work  correctly only when called inside of  an
  2983.            'If' loop.
  2984.  
  2985.  
  2986.       Declaration inside of an 'If' loop
  2987.       --------------------------------------------
  2988.  
  2989.            A variable or 'goto' label was declared  inside of an 'If' loop. This
  2990.            is not allowed.
  2991.  
  2992.  
  2993.  
  2994.  
  2995.  
  2996.  
  2997.  
  2998.  
  2999.  
  3000.  
  3001.  
  3002.       50                                                           Z/Install User's Guide
  3003.  
  3004.  
  3005.       Invalid Comparison
  3006.       --------------------------------------------
  3007.  
  3008.            An invalid 'If' comparison was  encountered.  This can happen if  two
  3009.            different types of data are compared.  For instance, an integer and a
  3010.            string cannot be compared to each other.
  3011.  
  3012.  
  3013.  
  3014.       GetInstallGroups called without any groups defined
  3015.       --------------------------------------------
  3016.  
  3017.            The function 'GetInstallGroups'  was called without any  groups being
  3018.            defined with the [GROUPS] information section.  GetInstallGroups will
  3019.            only have an effect if [GROUPS] is defined first.
  3020.  
  3021.  
  3022.       File group 'number' is not defined
  3023.       --------------------------------------------
  3024.  
  3025.            'SetFileGroup' was passed the number of a group that was not defined.
  3026.  
  3027.  
  3028.  
  3029.       'If' stack too big
  3030.       --------------------------------------------
  3031.  
  3032.            The 'If' loop level went over the maximum of 25.
  3033.  
  3034.  
  3035.       Too many integer/string variables
  3036.       --------------------------------------------
  3037.  
  3038.            There were too many integer or string variables declared.  There is a
  3039.            maximum of 50 each.
  3040.  
  3041.  
  3042.  
  3043.  
  3044.  
  3045.  
  3046.  
  3047.  
  3048.  
  3049.  
  3050.  
  3051.  
  3052.  
  3053.  
  3054.  
  3055.  
  3056.  
  3057.  
  3058.  
  3059.  
  3060.  
  3061.                                                                               51       SpeedSOFT Development                                                     
  3062.  
  3063.  
  3064.                                       Appendix D
  3065.  
  3066.       You can contact SpeedSOFT Development...
  3067.  
  3068.       By voice:
  3069.  
  3070.            (604) 472-0626
  3071.            9 am to 9 pm PST (voice)
  3072.  
  3073.       By mail:
  3074.  
  3075.            SpeedSOFT Development
  3076.            2232 Tashy Place
  3077.            Victoria, BC
  3078.            Canada
  3079.            V8N 4R6
  3080.  
  3081.       By Bulletin Board System:
  3082.  
  3083.            (604) 477-5337
  3084.            24 hours
  3085.            USR 16.8k Dual Standard
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.  
  3112.  
  3113.  
  3114.  
  3115.  
  3116.  
  3117.  
  3118.  
  3119.  
  3120.       52                                                           Z/Install User's Guide
  3121.  
  3122.  
  3123.                                          Index
  3124.  
  3125.       A
  3126.            archiving                                                           4
  3127.            Assignment                                                          6
  3128.            Auto-detection                                                     17
  3129.            Automation                                                          5
  3130.       B
  3131.            BASIC                                                               6
  3132.            Boxes                                                               6
  3133.       C
  3134.            Command-line                                                        4
  3135.            compiler                                                            4
  3136.            Compress                                                            4
  3137.            Constant                                                            6
  3138.       E
  3139.            Equals expression                                                   6
  3140.       F
  3141.            Functions                                                           6
  3142.       Functions
  3143.            AddAuto                                                            26
  3144.            AddConfig                                                          26
  3145.            BarMenu                                                            26
  3146.            BeginInstall                                                       27
  3147.            ChDir                                                              27
  3148.            CheckInstallOK                                                     28
  3149.            CloseFile                                                          29
  3150.            ClrScr                                                             29
  3151.            COMMENT.PAK                                                        22
  3152.            Copy                                                               29
  3153.            Delete                                                             30
  3154.            Dialog                                                             30
  3155.            DosCommand                                                         31
  3156.            ElIf                                                               31
  3157.            Else                                                               32
  3158.            EndIf                                                              32
  3159.            ExitScript                                                         32
  3160.            FileType                                                           32
  3161.            GetChoice                                                          33
  3162.            GetDir                                                             33
  3163.            GetDisk                                                            34
  3164.            GetVolumeLabel                                                     35
  3165.            GoSub                                                              36
  3166.            Goto                                                               36
  3167.            If                                                                 36
  3168.            Int                                                                37
  3169.            MarkFilesDate                                                      38
  3170.            MarkFilesTime                                                      38
  3171.            MkDir                                                              38
  3172.            ModPath                                                            39
  3173.            NetworkType                                                        39
  3174.            OpenFile                                                           40
  3175.            Pause                                                              40
  3176.            Print                                                              40
  3177.            ReBoot                                                             40
  3178.  
  3179.                                                                               53       SpeedSOFT Development                                                     
  3180.  
  3181.  
  3182.            RepeatRate                                                         40
  3183.            RestoreScreen                                                      41
  3184.            Return                                                             41
  3185.            RmDir                                                              42
  3186.            SaveScreen                                                         42
  3187.            SetBackChar                                                    16, 42
  3188.            SetBackColor                                                       16
  3189.            SetBuffers                                                         42
  3190.            SetDescLine                                                        43
  3191.            SetDialogColor                                                     16
  3192.            SetDialogStyle                                                     16
  3193.            SetDisk                                                            43
  3194.            SetEnv                                                             43
  3195.            SetExitMessage                                                 16, 44
  3196.            SetExplode                                                         16
  3197.            SetExplodeSnd                                                      16
  3198.            SetExplodeType                                                     16
  3199.            SetFileGroup                                                       44
  3200.            SetFiles                                                           44
  3201.            SetInputColor                                                      16
  3202.            SetInputFill                                                       16
  3203.            SetInputTplate                                                     44
  3204.            SetPrintColor                                                      16
  3205.            SetRestoreDOS                                                      45
  3206.            SetWarnColor                                                       16
  3207.            Str                                                                45
  3208.            UseBlink                                                           45
  3209.            ViewFile                                                           46
  3210.            WriteScreen                                                        47
  3211.            SetBarNormalColor                                                  16
  3212.            GetInstallationDrive                                               34
  3213.            GetInstallGroups                                                   35
  3214.            SetBarCharColor                                                    16
  3215.            SetBarHighColor                                                    16
  3216.            SetWarnTxtColor                                                    16
  3217.            SetAllowFixedSrc                                                   42
  3218.            UseHighIntensityBGColors                                           46
  3219.            SetDialogShadows                                                   16
  3220.       G
  3221.            Global variables                                                   17
  3222.       H
  3223.            HyperText                                                           4
  3224.       I
  3225.            Information section                                                17
  3226.            Installation executable                                             4
  3227.            Integer                                                             6
  3228.       J
  3229.            Junior SFX                                                         22
  3230.  
  3231.       54                                                           Z/Install User's Guide
  3232.  
  3233.  
  3234.       O
  3235.            OPTDist                                                             5
  3236.       Q
  3237.            Quotation marks                                                     6
  3238.       R
  3239.            Range, Integer                                                      6
  3240.            Return values                                                       6
  3241.       S
  3242.            SFX                                                                22
  3243.            String                                                              6
  3244.       T
  3245.            Textual User Interface                                              4
  3246.            TUI                                                                 4
  3247.       V
  3248.            Variables                                                           6
  3249.            VGA                                                                 4
  3250.       Z
  3251.            ZSL                                                                 6
  3252.  
  3253.  
  3254.  
  3255.  
  3256.  
  3257.  
  3258.  
  3259.  
  3260.  
  3261.  
  3262.  
  3263.  
  3264.  
  3265.  
  3266.  
  3267.  
  3268.  
  3269.  
  3270.  
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.  
  3277.  
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.                                                                               55
  3291.